blogwright-pds 0.1.0

package/dist/oauth.js

@@ -0,0 +1,176 @@
+/**
+ * atproto OAuth (confidential client) for standard.site publishing — the only
+ * module that touches @atproto/oauth-client-node. The blog itself is the OAuth
+ * client: its metadata + JWKS are static files on the site (client-metadata.ts),
+ * the private key and session live in the Secrets Manager secret (secret.ts),
+ * and every token refresh persists the rotated refresh token back there.
+ */
+import { JoseKey, NodeOAuthClient, OAuthResponseError, TokenRefreshError, TokenRevokedError, } from '@atproto/oauth-client-node';
+import { clientMetadata, clientMetadataUrl, jwksDocument, jwksUrl } from './client-metadata.js';
+import { loadPdsSecret, sessionStoreForSecret } from './secret.js';
+import { requirePdsConfig } from './sync.js';
+import { PdsClient } from './xrpc.js';
+const DEFAULT_HANDLE_RESOLVER = 'https://public.api.bsky.app';
+function requireDomain(ctx) {
+    if (!ctx.domain)
+        throw new Error('pds OAuth requires a configured domain');
+    return ctx.domain;
+}
+function requireClientKey(secret, pds) {
+    if (!secret.clientKey) {
+        throw new Error(`secret "${pds.secretName}" has no OAuth client key — run \`blogwright pds keygen\``);
+    }
+    return secret.clientKey;
+}
+/** The OAuth client, keyed with the secret's private JWK. */
+async function buildClient(ctx, clientKey) {
+    const pds = requirePdsConfig(ctx);
+    const states = new Map();
+    return new NodeOAuthClient({
+        clientMetadata: clientMetadata(requireDomain(ctx), pds),
+        keyset: [await JoseKey.fromJWK(clientKey)],
+        responseMode: 'query',
+        // The authorize → callback round-trip happens within one `pds login`
+        // process, so authorization state never needs to outlive it.
+        stateStore: {
+            get: async (key) => states.get(key),
+            set: async (key, state) => void states.set(key, state),
+            del: async (key) => void states.delete(key),
+        },
+        sessionStore: sessionStoreForSecret(ctx.clients.secrets, pds.secretName),
+        handleResolver: pds.handleResolver ?? DEFAULT_HANDLE_RESOLVER,
+        // Deliberately NO requestLock. The session lives in shared Secrets Manager
+        // state, and syncs can run concurrently (overlapping CI deploys). Providing
+        // a lock tells the library it holds the only instance, which disables its
+        // invalid_grant recovery (re-read the store and adopt a concurrently
+        // rotated session) and instead deletes the session — destroying the valid
+        // token a parallel sync just persisted. A process-local lock cannot
+        // serialize cross-process refreshes, so lock-less with recovery is correct.
+    });
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (a && b && typeof a === 'object' && typeof b === 'object') {
+        const ka = Object.keys(a).sort();
+        const kb = Object.keys(b).sort();
+        return (deepEqual(ka, kb) &&
+            ka.every((k) => deepEqual(a[k], b[k])));
+    }
+    return false;
+}
+/** A fresh ES256 private JWK for private_key_jwt client authentication. */
+export async function generateClientKey(kid) {
+    const key = await JoseKey.generate(['ES256'], kid);
+    const privateJwk = key.privateJwk;
+    if (!privateJwk)
+        throw new Error('generated key has no private JWK');
+    return JSON.parse(JSON.stringify(privateJwk));
+}
+/** Public half of the client key, for the served JWKS. */
+export async function publicClientJwk(clientKey) {
+    const key = await JoseKey.fromJWK(clientKey);
+    const publicJwk = (key.publicJwk ?? {});
+    const source = Object.keys(publicJwk).length > 0 ? publicJwk : clientKey;
+    // Round-trip through JSON: drops `d: undefined` left by the getter and
+    // matches exactly what the committed jwks.json file will contain.
+    const plain = JSON.parse(JSON.stringify(source));
+    delete plain.d;
+    return plain;
+}
+/**
+ * Check that the deployed /oauth/ documents match what this CLI would send the
+ * authorization server. Run before login/init — a stale or missing deployment
+ * would otherwise fail deep inside the OAuth flow.
+ */
+export async function verifyClientAssets(ctx, fetchImpl = fetch) {
+    const pds = requirePdsConfig(ctx);
+    const domain = requireDomain(ctx);
+    const secret = await loadPdsSecret(ctx);
+    const clientKey = requireClientKey(secret, pds);
+    const expectations = [
+        [clientMetadataUrl(domain), clientMetadata(domain, pds)],
+        [jwksUrl(domain), jwksDocument(await publicClientJwk(clientKey))],
+    ];
+    for (const [url, expected] of expectations) {
+        const res = await fetchImpl(url);
+        if (!res.ok) {
+            throw new Error(`${url} is not deployed (HTTP ${res.status}) — commit public/oauth/* and release first`);
+        }
+        let deployed;
+        try {
+            deployed = await res.json();
+        }
+        catch {
+            throw new Error(`${url} is not valid JSON — re-run \`blogwright pds keygen\` and redeploy`);
+        }
+        if (!deepEqual(deployed, expected)) {
+            throw new Error(`${url} does not match the local client configuration — ` +
+                're-run `blogwright pds keygen`, commit public/oauth/*, and release before logging in');
+        }
+    }
+}
+/**
+ * One-time interactive bootstrap: authorize in a browser, land on the site's
+ * /oauth/callback page, paste the redirect URL back. The client persists the
+ * session (and DID) into the secret through the session store.
+ */
+export async function login(ctx, identifier, deps) {
+    await (deps.verifyAssets ?? verifyClientAssets)(ctx);
+    let flow = deps.flow;
+    if (!flow) {
+        const secret = await loadPdsSecret(ctx);
+        flow = await buildClient(ctx, requireClientKey(secret, requirePdsConfig(ctx)));
+    }
+    const url = await flow.authorize(identifier);
+    ctx.logger.info('Open this URL in a browser and approve access:');
+    ctx.logger.info(`  ${url.toString()}`);
+    const pasted = await deps.promptLine('Paste the full URL of the /oauth/callback page you landed on: ');
+    let params;
+    try {
+        params = new URL(pasted.trim()).searchParams;
+    }
+    catch {
+        throw new Error('that was not a URL — paste the full callback address, query string and all');
+    }
+    if (params.get('error')) {
+        throw new Error(`authorization failed: ${params.get('error')} — ${params.get('error_description') ?? ''}`);
+    }
+    const { session } = await flow.callback(params);
+    ctx.logger.ok(`logged in as ${session.did}`);
+    return session.did;
+}
+function sessionExpired(err) {
+    if (err instanceof TokenRefreshError || err instanceof TokenRevokedError)
+        return true;
+    return err instanceof OAuthResponseError && err.error === 'invalid_grant';
+}
+/**
+ * Restore the stored OAuth session (transparently refreshing — the rotated
+ * refresh token lands back in the secret) and wrap it as a PdsClient. The
+ * session's fetchHandler adds DPoP + auth headers and handles nonce retries.
+ */
+export async function openPdsRepo(ctx) {
+    const pds = requirePdsConfig(ctx);
+    const secret = await loadPdsSecret(ctx);
+    const clientKey = requireClientKey(secret, pds);
+    if (!secret.did || !secret.session) {
+        throw new Error(`secret "${pds.secretName}" has no OAuth session — run \`blogwright pds login\``);
+    }
+    const client = await buildClient(ctx, clientKey);
+    try {
+        const session = await client.restore(secret.did);
+        return { did: secret.did, repo: new PdsClient(secret.did, session.fetchHandler.bind(session)) };
+    }
+    catch (err) {
+        if (sessionExpired(err)) {
+            throw new Error('the stored OAuth session is no longer valid (refresh tokens expire after 180 idle ' +
+                'days, and rotation races invalidate them) — re-run `blogwright pds login`', { cause: err });
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=oauth.js.map

package/dist/oauth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.js","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,OAAO,EACP,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,GAGlB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEhG,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAkB,MAAM,aAAa,CAAC;AACnF,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,uBAAuB,GAAG,6BAA6B,CAAC;AAE9D,SAAS,aAAa,CAAC,GAAe;IACpC,IAAI,CAAC,GAAG,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAC3E,OAAO,GAAG,CAAC,MAAM,CAAC;AACpB,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAiB,EAAE,GAAc;IACzD,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,WAAW,GAAG,CAAC,UAAU,2DAA2D,CACrF,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,SAAS,CAAC;AAC1B,CAAC;AAED,6DAA6D;AAC7D,KAAK,UAAU,WAAW,CAAC,GAAe,EAAE,SAAc;IACxD,MAAM,GAAG,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,IAAI,GAAG,EAA0B,CAAC;IACjD,OAAO,IAAI,eAAe,CAAC;QACzB,cAAc,EAAE,cAAc,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;QACvD,MAAM,EAAE,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,SAAoC,CAAC,CAAC;QACrE,YAAY,EAAE,OAAO;QACrB,qEAAqE;QACrE,6DAA6D;QAC7D,UAAU,EAAE;YACV,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;YACnC,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC;YACtD,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC;SAC5C;QACD,YAAY,EAAE,qBAAqB,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,UAAU,CAAC;QACxE,cAAc,EAAE,GAAG,CAAC,cAAc,IAAI,uBAAuB;QAC7D,2EAA2E;QAC3E,4EAA4E;QAC5E,0EAA0E;QAC1E,qEAAqE;QACrE,0EAA0E;QAC1E,oEAAoE;QACpE,4EAA4E;KAC7E,CAAC,CAAC;AACL,CAAC;AAED,SAAS,SAAS,CAAC,CAAU,EAAE,CAAU;IACvC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC7D,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACjC,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACjC,OAAO,CACL,SAAS,CAAC,EAAE,EAAE,EAAE,CAAC;YACjB,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CACb,SAAS,CAAE,CAA6B,CAAC,CAAC,CAAC,EAAG,CAA6B,CAAC,CAAC,CAAC,CAAC,CAChF,CACF,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,GAAW;IACjD,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,CAAC;IACnD,MAAM,UAAU,GAAG,GAAG,CAAC,UAAU,CAAC;IAClC,IAAI,CAAC,UAAU;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACrE,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAQ,CAAC;AACvD,CAAC;AAED,0DAA0D;AAC1D,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,SAAc;IAClD,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,SAAoC,CAAC,CAAC;IACxE,MAAM,SAAS,GAAG,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAA4B,CAAC;IACnE,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IACzE,uEAAuE;IACvE,kEAAkE;IAClE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAA4B,CAAC;IAC5E,OAAO,KAAK,CAAC,CAAC,CAAC;IACf,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,GAAe,EACf,YAA0B,KAAK;IAE/B,MAAM,GAAG,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,SAAS,GAAG,gBAAgB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAChD,MAAM,YAAY,GAAuC;QACvD,CAAC,iBAAiB,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACxD,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC,MAAM,eAAe,CAAC,SAAS,CAAC,CAAC,CAAC;KAClE,CAAC;IACF,KAAK,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,YAAY,EAAE,CAAC;QAC3C,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,GAAG,GAAG,0BAA0B,GAAG,CAAC,MAAM,6CAA6C,CACxF,CAAC;QACJ,CAAC;QACD,IAAI,QAAiB,CAAC;QACtB,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,KAAK,CAAC,GAAG,GAAG,oEAAoE,CAAC,CAAC;QAC9F,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CACb,GAAG,GAAG,mDAAmD;gBACvD,sFAAsF,CACzF,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAeD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,GAAe,EAAE,UAAkB,EAAE,IAAe;IAC9E,MAAM,CAAC,IAAI,CAAC,YAAY,IAAI,kBAAkB,CAAC,CAAC,GAAG,CAAC,CAAC;IACrD,IAAI,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACrB,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,GAAG,MAAM,WAAW,CAAC,GAAG,EAAE,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACjF,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IAC7C,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAC;IAClE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAClC,gEAAgE,CACjE,CAAC;IACF,IAAI,MAAuB,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,4EAA4E,CAAC,CAAC;IAChG,CAAC;IACD,IAAI,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,yBAAyB,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,IAAI,EAAE,EAAE,CAC1F,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChD,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,gBAAgB,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAC7C,OAAO,OAAO,CAAC,GAAG,CAAC;AACrB,CAAC;AAED,SAAS,cAAc,CAAC,GAAY;IAClC,IAAI,GAAG,YAAY,iBAAiB,IAAI,GAAG,YAAY,iBAAiB;QAAE,OAAO,IAAI,CAAC;IACtF,OAAO,GAAG,YAAY,kBAAkB,IAAI,GAAG,CAAC,KAAK,KAAK,eAAe,CAAC;AAC5E,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAe;IAC/C,MAAM,GAAG,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,SAAS,GAAG,gBAAgB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACb,WAAW,GAAG,CAAC,UAAU,uDAAuD,CACjF,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACjD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjD,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;IAClG,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CACb,oFAAoF;gBAClF,2EAA2E,EAC7E,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/rkey.d.ts

@@ -0,0 +1,24 @@
+/**
+ * URL-derived AT Protocol record keys for standard.site documents.
+ *
+ * `tidFromPath`, `extractDate`, `hashBits`, and `encodeTid` are vendored from
+ * https://github.com/mastrojs/atproto (src/rkey.ts), MIT License, © 2025 Mastro.
+ * Behaviour must not diverge: rkeys derived here must match link tags any
+ * standard.site-aware client reconstructs with the reference implementation.
+ *
+ * Exported from the package as the `./rkey` subpath so the consuming site can
+ * derive its document <link> tags from the same implementation. rkey.test.ts pins
+ * the outputs to on-the-wire vectors that must never change for an existing path.
+ */
+/** Derive a TID-format rkey from a URL path (deterministic, no PDS round-trip). */
+export declare const tidFromPath: (path: string) => string;
+/** Exported only for tests. */
+export declare const extractDate: (path: string) => string | undefined;
+/**
+ * Canonical URL path for a blog post — the shape `src/pages/posts/index.astro` links
+ * (trailing slash). Rkeys derive from this string, so slugs must never change after
+ * publication.
+ */
+export declare const postPath: (slug: string) => string;
+/** AT-URI of the standard.site document record for a post. */
+export declare const documentUri: (did: string, slug: string) => string;

package/dist/rkey.js

@@ -0,0 +1,79 @@
+/**
+ * URL-derived AT Protocol record keys for standard.site documents.
+ *
+ * `tidFromPath`, `extractDate`, `hashBits`, and `encodeTid` are vendored from
+ * https://github.com/mastrojs/atproto (src/rkey.ts), MIT License, © 2025 Mastro.
+ * Behaviour must not diverge: rkeys derived here must match link tags any
+ * standard.site-aware client reconstructs with the reference implementation.
+ *
+ * Exported from the package as the `./rkey` subpath so the consuming site can
+ * derive its document <link> tags from the same implementation. rkey.test.ts pins
+ * the outputs to on-the-wire vectors that must never change for an existing path.
+ */
+/** Derive a TID-format rkey from a URL path (deterministic, no PDS round-trip). */
+export const tidFromPath = (path) => {
+    if (path.replaceAll('/', '').length === 0) {
+        throw Error(`tidFromPath received empty path (after slashes were removed): ${path}`);
+    }
+    const dateStr = extractDate(path);
+    // TID: 64-bit int (bit 63 = 0)
+    // - bits 62-10 = microsecond timestamp (53 bits)
+    // - bits 9-0 = clock ID (10 bits)
+    let tid;
+    if (dateStr) {
+        const date = new Date(dateStr);
+        if (Number.isNaN(date.getTime())) {
+            // A date-like digit pattern that is not a real date (e.g. a product
+            // slug "sku-3456-78-90"). The reference implementation throws here, so
+            // no existing record can hold a date-derived TID for such a path —
+            // falling back to the whole-path hash cannot diverge from live rkeys.
+            tid = hashBits(path, 63);
+        }
+        else {
+            const micros = (BigInt(date.getTime()) * 1000n) & ((1n << 53n) - 1n);
+            const clockId = hashBits(path, 10);
+            tid = (micros << 10n) | clockId;
+        }
+    }
+    else {
+        tid = hashBits(path, 63);
+    }
+    return encodeTid(tid);
+};
+/** Exported only for tests. */
+export const extractDate = (path) => {
+    const m = path.match(/(\d{4})[/-](\d{2})[/-](\d{2})/);
+    if (m) {
+        return `${m[1]}-${m[2]}-${m[3]}`;
+    }
+    return undefined;
+};
+/** FNV-1a hash truncated to `nrOfBits` bits. */
+const hashBits = (s, nrOfBits) => {
+    const mask = (1n << BigInt(nrOfBits)) - 1n;
+    let h = 0xcbf29ce484222325n;
+    for (let i = 0; i < s.length; i++) {
+        h ^= BigInt(s.charCodeAt(i));
+        h = (h * 0x100000001b3n) & 0xffffffffffffffffn;
+    }
+    return h & mask;
+};
+const encodeTid = (n) => {
+    let result = '';
+    for (let i = 0; i < 13; i++) {
+        result = BASE32[Number(n & 31n)] + result;
+        n >>= 5n;
+    }
+    return result;
+};
+const BASE32 = '234567abcdefghijklmnopqrstuvwxyz';
+// --- example-specific helpers (not vendored) ---
+/**
+ * Canonical URL path for a blog post — the shape `src/pages/posts/index.astro` links
+ * (trailing slash). Rkeys derive from this string, so slugs must never change after
+ * publication.
+ */
+export const postPath = (slug) => `/posts/${slug}/`;
+/** AT-URI of the standard.site document record for a post. */
+export const documentUri = (did, slug) => `at://${did}/site.standard.document/${tidFromPath(postPath(slug))}`;
+//# sourceMappingURL=rkey.js.map

package/dist/rkey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rkey.js","sourceRoot":"","sources":["../src/rkey.ts"],"names":[],"mappings":"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"}

package/dist/secret.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The Secrets Manager secret backing standard.site publishing: one JSON value
+ * holding the OAuth confidential-client private key, the account DID, and the
+ * current OAuth session (rotated on every token refresh).
+ *
+ * Writers: `pds keygen` (clientKey, clears session), `pds login` (session+did),
+ * and the session store below whenever the OAuth client refreshes tokens.
+ */
+import type { Jwk, NodeSavedSession, NodeSavedSessionStore } from '@atproto/oauth-client-node';
+import type { SecretsManagerClient } from 'blogwright-core';
+import type { PdsContext } from './context.js';
+/** The client surface secret persistence needs — structural, so tests can stub it. */
+export type SecretsStore = Pick<SecretsManagerClient, 'getSecretValue' | 'upsertSecret'>;
+export interface PdsSecret {
+    version: 1;
+    /** Private ES256 JWK authenticating the OAuth client (private_key_jwt). */
+    clientKey?: Jwk | undefined;
+    /** Account DID; set by `pds login`, checked against src/data/atproto.json. */
+    did?: string | undefined;
+    /** Current OAuth session (token set + DPoP key); rotates on refresh. */
+    session?: NodeSavedSession | undefined;
+}
+/** Parse the secret JSON, rejecting the pre-OAuth app-password shape. */
+export declare function parsePdsSecret(raw: string, secretName: string): PdsSecret;
+/**
+ * Fetch and parse the secret. Called only at keygen/login/sync time —
+ * secret material must never be loaded during context creation.
+ */
+export declare function loadPdsSecret(ctx: PdsContext): Promise<PdsSecret>;
+/**
+ * Read-modify-write the secret; starts from an empty v1 value when absent.
+ * `replaceLegacy` lets keygen start over from a pre-OAuth app-password value —
+ * the migration entry point; every other writer must reject it.
+ */
+export declare function updatePdsSecret(secrets: SecretsStore, secretName: string, mutate: (secret: PdsSecret) => PdsSecret, opts?: {
+    replaceLegacy?: boolean;
+}): Promise<PdsSecret>;
+/**
+ * NodeOAuthClient session store backed by the secret. `set` runs on login and
+ * on every refresh-token rotation — persisting it is what keeps the CI session
+ * alive; `del` clears only the session (client key and DID survive a logout).
+ */
+export declare function sessionStoreForSecret(secrets: SecretsStore, secretName: string): NodeSavedSessionStore;

package/dist/secret.js

@@ -0,0 +1,109 @@
+/**
+ * The Secrets Manager secret backing standard.site publishing: one JSON value
+ * holding the OAuth confidential-client private key, the account DID, and the
+ * current OAuth session (rotated on every token refresh).
+ *
+ * Writers: `pds keygen` (clientKey, clears session), `pds login` (session+did),
+ * and the session store below whenever the OAuth client refreshes tokens.
+ */
+import { requirePdsConfig } from './sync.js';
+const SECRET_DESCRIPTION = 'AT Protocol OAuth client key + session for standard.site publishing (blogwright pds)';
+function parseJsonObject(raw, secretName) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`secret "${secretName}" is not valid JSON`);
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`secret "${secretName}" is not a JSON object`);
+    }
+    return parsed;
+}
+/** The pre-OAuth `{ identifier, password }` shape, replaced only by keygen. */
+function isLegacySecret(parsed) {
+    return 'identifier' in parsed || 'password' in parsed;
+}
+/** Parse the secret JSON, rejecting the pre-OAuth app-password shape. */
+export function parsePdsSecret(raw, secretName) {
+    const parsed = parseJsonObject(raw, secretName);
+    if (isLegacySecret(parsed)) {
+        throw new Error(`secret "${secretName}" holds app-password credentials — app passwords are no longer ` +
+            'supported; run `blogwright pds keygen` then `blogwright pds login`');
+    }
+    if (parsed.version !== 1) {
+        throw new Error(`secret "${secretName}" has unsupported version ${String(parsed.version)}`);
+    }
+    return parsed;
+}
+/**
+ * Fetch and parse the secret. Called only at keygen/login/sync time —
+ * secret material must never be loaded during context creation.
+ */
+export async function loadPdsSecret(ctx) {
+    const pds = requirePdsConfig(ctx);
+    const raw = await ctx.clients.secrets.getSecretValue(pds.secretName);
+    if (!raw) {
+        throw new Error(`no secret at "${pds.secretName}" — create it with \`blogwright pds keygen\``);
+    }
+    return parsePdsSecret(raw, pds.secretName);
+}
+/**
+ * Read-modify-write the secret; starts from an empty v1 value when absent.
+ * `replaceLegacy` lets keygen start over from a pre-OAuth app-password value —
+ * the migration entry point; every other writer must reject it.
+ */
+export async function updatePdsSecret(secrets, secretName, mutate, opts = {}) {
+    const raw = await secrets.getSecretValue(secretName);
+    const current = !raw || (opts.replaceLegacy && isLegacySecret(parseJsonObject(raw, secretName)))
+        ? { version: 1 }
+        : parsePdsSecret(raw, secretName);
+    const next = mutate(current);
+    await secrets.upsertSecret(secretName, JSON.stringify(next), SECRET_DESCRIPTION);
+    return next;
+}
+/**
+ * NodeOAuthClient session store backed by the secret. `set` runs on login and
+ * on every refresh-token rotation — persisting it is what keeps the CI session
+ * alive; `del` clears only the session (client key and DID survive a logout).
+ */
+export function sessionStoreForSecret(secrets, secretName) {
+    return {
+        async get(sub) {
+            const raw = await secrets.getSecretValue(secretName);
+            if (!raw)
+                return undefined;
+            const secret = parsePdsSecret(raw, secretName);
+            if (secret.did !== sub)
+                return undefined;
+            return secret.session;
+        },
+        async set(sub, session) {
+            // Retried: this write persists a just-rotated single-use refresh token.
+            // If it throws, the OAuth library revokes the new token and deletes the
+            // session — one Secrets Manager throttle at exactly the wrong moment
+            // would otherwise force an interactive re-login.
+            let lastError;
+            for (let attempt = 0; attempt < 3; attempt++) {
+                try {
+                    await updatePdsSecret(secrets, secretName, (secret) => ({
+                        ...secret,
+                        did: sub,
+                        session,
+                    }));
+                    return;
+                }
+                catch (err) {
+                    lastError = err;
+                    await new Promise((r) => setTimeout(r, 250 * (attempt + 1)));
+                }
+            }
+            throw lastError;
+        },
+        async del(sub) {
+            await updatePdsSecret(secrets, secretName, (secret) => secret.did === sub ? { ...secret, session: undefined } : secret);
+        },
+    };
+}
+//# sourceMappingURL=secret.js.map

package/dist/secret.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret.js","sourceRoot":"","sources":["../src/secret.ts"],"names":[],"mappings":"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"}

package/dist/sync.d.ts

@@ -0,0 +1,55 @@
+import { type FileSystem, type OpsConfig, type PdsConfig } from 'blogwright-core';
+import { type PostMeta } from './content.js';
+import type { PdsContext } from './context.js';
+import { type PdsClient } from './xrpc.js';
+/** The client surface the sync needs — structural, so tests can stub it. */
+export type PdsRepo = Pick<PdsClient, 'listRecords' | 'getRecord' | 'putRecord'>;
+/**
+ * Opens an authenticated repo for the configured account. Production wiring is
+ * oauth.ts#openPdsRepo (OAuth session restore); tests inject stubs.
+ */
+export type OpenRepo = (ctx: PdsContext) => Promise<{
+    did: string;
+    repo: PdsRepo;
+}>;
+export declare const PUBLICATION_COLLECTION = "site.standard.publication";
+export declare const DOCUMENT_COLLECTION = "site.standard.document";
+/**
+ * Repo-relative path of the standard.site well-known file `pds init` writes;
+ * its segment under the public dir is protocol-fixed. The companion
+ * atproto.json path comes straight from `config.paths.atprotoJson`.
+ */
+export declare function wellKnownPath(cfg: Pick<OpsConfig, 'paths'>): string;
+export interface SyncSummary {
+    publication: 'updated' | 'unchanged';
+    created: string[];
+    updated: string[];
+    unchanged: number;
+    /** rkeys of PDS document records with no matching local post (never deleted). */
+    orphans: string[];
+}
+export declare function requirePdsConfig(ctx: PdsContext): PdsConfig;
+/** Read the committed well-known file; undefined when absent. */
+export declare function readWellKnownUri(fs: FileSystem, repoRoot: string, cfg: Pick<OpsConfig, 'paths'>): Promise<string | undefined>;
+/**
+ * The publication record as config + domain describe it. `siteUrl` must have
+ * no trailing slash — standard.site appends the document `path`, which already
+ * starts with one.
+ */
+export declare function publicationRecord(pds: PdsConfig, siteUrl: string): Record<string, unknown>;
+/** The document record for a post. */
+export declare function documentRecord(publicationUri: string, post: PostMeta): Record<string, unknown>;
+/** Put the publication record when it differs from (or is missing at) its rkey. */
+export declare function syncPublication(client: PdsRepo, desired: Record<string, unknown>, publicationUri: string): Promise<'updated' | 'unchanged'>;
+/**
+ * Reconcile document records against the local posts: create missing rkeys,
+ * update drifted ones, report (never delete) orphans. Adapted from
+ * mastrojs/atproto createOrUpdateDocuments (MIT) onto the local XRPC client.
+ */
+export declare function syncDocuments(client: PdsRepo, posts: PostMeta[], publicationUri: string): Promise<Omit<SyncSummary, 'publication'>>;
+/**
+ * Full reconcile: OAuth session restore against the PDS, publication +
+ * documents. The caller decides when this may run (production only) and
+ * whether a failure is fatal.
+ */
+export declare function syncPds(ctx: PdsContext, repoRoot: string, openRepo: OpenRepo): Promise<SyncSummary>;