@danj/audible-auth

Locked Audible credential gateway: Connect, token refresh, and narrow Audible calls for other Kody packages.

README.md

129 lines · 6.6 KB · Markdown

@danj/audible-auth

Intent

Handle a reader's Audible credentials so that other Kody packages can use a small set of Audible services without ever reading a token. The package is publish-locked: a change goes live only after the owner reviews the diff and clicks Promote this commit.

Services

Service	What it does for the caller	Call it makes
Connect page (the package app)	Connect: creates the Amazon login link, takes the maplanding URL, registers a virtual Audible device, and stores its tokens. When this package already had a device, it removes that device from your Amazon account. Disconnect: removes the device from your Amazon account and deletes both token secrets.	Amazon `/auth/register`, `/auth/deregister`
`./status`	Reports the connection, the hosts still to allow (with one-click links), and the NAS archive state. Metadata only.	One Library call, until the hosts are proven
`./request`	Library list or one item; Wishlist list, add, or remove. Throws on any other call.	`GET /1.0/library`, `GET /1.0/library/<asin>`, `GET /1.0/wishlist`, `POST /1.0/wishlist`, `DELETE /1.0/wishlist/<asin>`
`./credits`	The plan's next charge and the credit balance: numbers and a date, no account details.	`GET /1.0/account/information`
`./license`	NAS archive: an AAXC download license and its decrypted key for one owned Book. Works only while NAS archive is on; see NAS archive.	`POST /1.0/content/<asin>/licenserequest`

Each service refreshes the hourly access token when it needs to. Callers never handle a token.

Use your own copy

Each Kody account needs its own copy of this package: a copy holds one owner's credentials. Your agent guides you through these steps.

Your agent forks this package into your account.
Your agent replaces every @danj/ reference in the copy (this README, AGENTS.md, and the import examples in src/) with your own scope, and commits that before anything else. LICENSE and the credits in NOTICE stay as they are.
You lock your fork right away: open its page on Kody and click the lock icon, or let your agent lock it. An unlocked fork lets any later push change the code that handles your credentials, with no review.
Your agent points your apps' kody.dependencies and imports at your fork's scope.
You connect on your fork's Connect page, and allow the hosts it lists.
From then on, each change to your fork waits for your Promote this commit click.

Use it from another package

The agent that builds your package follows these steps to use this package's services.

Add "@<your-scope>/audible-auth": "*" to kody.dependencies, and import the exports as kody:@<your-scope>/audible-auth/<export>. Your scope is the one of your own copy (see above).
To connect, link the owner to the Connect page: https://<username>.kody.run/packages/audible-auth/?return=<your app URL>. The page shows a Back to the app link when return is an app on the same Kody host.
Use the other services once ./status returns ready: true. Until then, show the owner the link to the Connect page.

Only this package's own page creates an Amazon login link, so the link always comes from reviewed code.

Your package bundles a snapshot of this one. After each promote here, republish your package.

NAS archive

NAS archive is the feature that saves Books the owner owns to their NAS. Audible gives the download license only to a request signed with the device's ADP token and private key. Only Connect receives that key, from Amazon.

	NAS archive off (default)	NAS archive on
ADP token and private key	Connect discards them	Connect stores them in package storage
`./license`	Throws `ArchiveDisabledError`	Signs the license request and decrypts the Book's content key

ARCHIVE_ENABLED in src/config.ts is the switch.

Turning NAS archive on

Your agent sets ARCHIVE_ENABLED to true in src/config.ts, commits, and pushes.
You review the diff and click Promote this commit.
Your agent republishes the packages that use this one.
You connect again on the Connect page, so Amazon issues a new signing key.

To turn it off, your agent sets ARCHIVE_ENABLED back to false, you promote, and you connect again: that Connect discards the stored key.

Security posture

Credential	Where it lives	What can read it
Refresh token	Package secret `audible-refresh-token`	Nothing. Kody sends it only to `api.amazon.<domain>`.
Access token (60 minutes)	Package secret `audible-access-token`, with expiry	This package's code, for a moment at each refresh. Kody sends it only to `api.audible.<domain>` and `api.amazon.<domain>`.
ADP token and private key	NAS archive off: nowhere. NAS archive on: package storage `archive-signing-v1`.	NAS archive on: this package's code, to sign license requests.
Amazon cookies	Never requested	Nothing
Device serial, device type, customer id	Package storage `device-v1`	This package's code. These are identifiers, not secrets.

What this design guarantees:

Only the locked Connect page creates an Amazon login link. A calling package cannot swap in a link that would register an attacker's device.
Callers, and the agents that work on them, get services, never tokens. They cannot add an Audible call: the list lives in src/policy.ts, and a change there needs the owner's promote.
No service can buy a Book or read account details.
Kody approves each token's hosts only through the owner's click.

What it leaves open:

Connect and Disconnect remove only the device this package registered. Other "Audible for iPhone" devices stay in your Amazon account's device list until you remove them there.
A login link from anywhere else, such as a chat message, can still phish you. Start Connect only from this package's page, and after each Connect check that your Amazon account lists one "Audible for iPhone" device for this setup.
Connect holds every credential in memory once, until it stores them.
Each refresh holds the new access token in memory until secretSet stores it.
Any code that imports the exports can use the services: browse the Library, change the Wishlist, and read credit numbers.

License

AGPL-3.0-only; see LICENSE. The Audible login, registration, signing, and voucher logic follows mkb79/Audible (AGPL-3.0), by way of Kent C. Dodds' MIT-licensed TypeScript port in @kentcdodds/audible on Kody. NOTICE credits both and keeps Kent's license notice.