OAuth

​

Credential owners

• The app ({ owner: 'app' }): one credential the agent uses for everybody, such as a service account or a bot installation.
• A user ({ owner: 'user', principalId, issuer? }): one credential per signed-in person. principalId is the user’s id and issuer names the identity provider that issued it, so alice from one issuer and alice from another are different owners. With route auth, a request’s principal maps onto it as { owner: 'user', principalId: principal.id, issuer: principal.issuer }; a user credential needs that principal, because without one there is no user to own it.

import { tokenStoreKey } from '@lousho/build-ai-agent';

tokenStoreKey('github', { owner: 'app' }); // 'github|app'
tokenStoreKey('github', { owner: 'user', principalId: 'a|b', issuer: 'https://id.example.com' });
// 'github|user|https%3A%2F%2Fid.example.com|a%7Cb'

​

Token storage

import { memoryStore } from '@lousho/build-ai-agent';

const { tokens } = memoryStore();
const alice = { owner: 'user', principalId: 'alice', issuer: 'https://id.example.com' } as const;

await tokens.set('github', alice, { accessToken: 'gho_...', refreshToken: 'ghr_...', tokenType: 'Bearer', expiresAt: Date.now() + 3_600_000 });
const token = await tokens.get('github', alice); // { accessToken, refreshToken, ... } or undefined
const connected = await tokens.list({ owner: alice }); // [{ provider: 'github', owner, expiresAt, scope, hasRefreshToken: true, updatedAt }]
await tokens.delete('github', alice); // disconnect

• get, set and delete read, write (replacing) and remove one credential.
• list({ provider?, owner? }) returns metadata only: provider, owner, token type, expiry, scope, whether a refresh token is stored, and when the record was written. It never returns an access or refresh token.
• putPending(state, value, ttlMs) and takePending(state) keep a sign-in in progress (the PKCE verifier and where to return) between the redirect and the callback. takePending returns it once and deletes it; after ttlMs it is gone. state is 16-128 characters from A-Z, a-z, 0-9, _ and -; a malformed state passed to takePending is simply not found.
• setClient(provider, client) and getClient(provider) keep a client registered with an authorization server (dynamic client registration). The record may hold a client secret, so it is encrypted like a token.

node -e "console.log(Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString('base64'))"

import { createAgent, fileStore, generateTokenKey } from '@lousho/build-ai-agent';

console.log(generateTokenKey()); // store it as a secret, e.g. LOUSHO_TOKEN_KEY

const agent = createAgent({ provider, store: fileStore('./.lousho', { tokenKey: process.env.LOUSHO_TOKEN_KEY }) });

• A key that is not exactly 32 bytes of base64 is a ConfigurationError when the store is built.
• With no key, an agent that never stores a token works as before: reads find nothing. The first set, setClient or putPending throws LOUSHO_TOKEN_KEY_MISSING, and so does reading a record that exists.
• Each write uses a fresh random 12-byte IV, so the same token written twice gives two different ciphertexts. The record key is authenticated with it: a ciphertext copied to another owner’s row does not decrypt. The stored form is v1.<base64 iv>.<base64 ciphertext>.
• A record written under another key, or changed on disk, fails with LOUSHO_TOKEN_DECRYPT_FAILED, which names the provider and never the token.