@danj/audible-auth

@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

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.

1. Your agent forks this package into your account.
2. 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.
3. 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.
4. Your agent points your apps' kody.dependencies and imports at your fork's scope.
5. You connect on your fork's Connect page, and allow the hosts it lists.
6. 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.

1. 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).
2. 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.
3. 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.

ARCHIVE_ENABLED in src/config.ts is the switch.

Turning NAS archive on

1. Your agent sets ARCHIVE_ENABLED to true in src/config.ts, commits, and pushes.
2. You review the diff and click Promote this commit.
3. Your agent republishes the packages that use this one.
4. 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

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.