@poppykit/client 0.0.0-stage → 0.1.0

package/RELEASING.md

@@ -0,0 +1,193 @@
+# Release preparation and owner runbook
+
+The owner selected the **MIT** license and initial development version **0.1.0**.
+`private: false`, `publishConfig.access: public` and the shipped [LICENSE](LICENSE)
+prepare these candidates for a public release; they do not publish anything.
+No package has been published. Tags, npm publication and external settings remain
+separate owner-authorized actions. This is an initial 0.x release, not a stable 1.0
+compatibility promise.
+
+## Verification graph
+
+Every push, pull request and manual CI run calls the same repository-local
+`.github/workflows/verify.yml`. Documentation-only changes run the graph too;
+there are no path filters. A clean GitHub-hosted Linux job builds and packs once.
+The release manifest binds full source SHAs, package/version, filenames, byte
+counts, SHA256 and npm SHA512 integrity to those unchanged tarballs.
+
+| Job | Responsibility |
+| --- | --- |
+| candidate | Typecheck/build from exact source, pack once, record/upload identity |
+| fast | Documentation links/fences and small unit checks |
+| contracts | Storage, authentication, network and conversation contracts |
+| integration | API/browser/feedback and independent peers; CLI installs all pinned candidates |
+| packaged-linux/windows/macos | Install unchanged tarballs; startup, exports, SQLite and representative platform behavior |
+| validation | Release failure simulations, registry/toolchain guards and actual workflow wiring assertions |
+| gate | Always report; require each allowlisted job result to equal success and recheck artifact identity |
+
+The candidate job strictly typechecks and compiles the complete TypeScript test
+harness once before packing. It uploads a separate same-run `test-harness`
+artifact, never inside an npm candidate. Each unprivileged test/OS job checks the
+full source commit, complete canonical source inventory, exact LF source hashes
+and exact emitted-output hashes before using that harness. Runtime/packaged checks
+still import the unchanged candidate's installed JavaScript and execute real npm
+shims. The publisher consumes only tested npm tarballs and never the harness.
+
+All deterministic source tests run once on Linux, partitioned by
+`.github/test-groups.json`. Its runner rejects unassigned/duplicate test files.
+The CLI does not rerun complete SDK suites. It checks out the exact full client
+and server SHAs in its candidate JSON files, builds/installs their tarballs, and
+tests the combined package boundary. The SDKs have no dependency on one another;
+the server candidate is a CLI integration peer, not a production CLI dependency.
+Private cross-repository checkouts require owner-provided read access; no local
+untracked sibling directory is assumed.
+
+Node 24.12.0 is the supported CI baseline on GitHub-hosted ubuntu-latest,
+windows-latest and macos-latest. Later Node majors are not separately certified.
+The CLI checks unsupported Node 22.17.1 once on Linux. Most JavaScript/type checks
+do not need an OS-by-runtime matrix. Packaged OS checks exercise installed shims,
+paths/SQLite and the CLI's generic encrypted-backend/lifecycle fixture. They do
+not certify a production OS keyring, physical terminal, browser engine or KMS.
+
+SDK ordinary CI may restore a pnpm cache keyed by its frozen lockfile; installed
+dependencies are never shared across OSes. Release-context verification restores
+no dependency cache. The unpublished CLI dependency is supplied explicitly as a
+tarball; SDK lockfiles and full commit/version pins govern inputs, with exact
+TypeScript 5.9.3/@types-node 24.10.0/undici-types 7.16.0 tooling. No privileged
+release consumes a pull-request cache, artifact or check-name lookup. Artifacts
+are downloaded from this run only, and their manifest digest comes from the
+candidate job output. Failure logs retain seven days; candidates retain fourteen.
+Expired/missing artifacts require a new complete verification run.
+
+## Release workflow and fail-closed gate
+
+`release.yml` is manual dispatch only. Dispatch an existing owner-approved
+`vVERSION` tag, supply the full tagged commit, matching version/tag, and
+leave `publish=false` for verification only. A branch dispatch, wrong SHA,
+version/tag mismatch, moved tag or missing/changed artifact is rejected. Do not
+push a tag merely to test workflow syntax. All actions are pinned to immutable
+commits; reusable verification is the same commit as its caller.
+
+The allowlist is candidate, fast, contracts, integration, packaged-linux,
+packaged-windows, packaged-macos and validation. Missing, empty, failed, canceled
+and skipped results all fail. The always-running gate has no permission to
+publish. The publisher needs the reusable verification workflow to succeed AND
+its ready output to be exactly true AND explicit publish selection. It then
+rechecks source/commit/ref/version, manifest digest, every tarball, unchanged
+packed metadata, private/license policy, npm/toolchain and registry state.
+
+Only the publishing job requests `id-token: write`. It runs on GitHub-hosted
+Linux in protected environment `npm`. There is no publish credential in PR CI,
+no workflow_run artifact promotion, no checkout of PR code in a privileged job,
+no build/install/pack in the publisher, and no automatic publication on push/tag.
+Publication uses `npm publish TESTED_TARBALL --access public --provenance --ignore-scripts`.
+It publishes the unchanged bytes downloaded and checked in that job. Publication
+is serialized per repository and is never canceled by a newer release run.
+
+Safe local tests execute the gate with failed/canceled/missing/skipped checks,
+wrong commit/version/tag/ref, missing artifact, tampered tarball/manifest and an
+absent trusted digest. Registry tests reject an existing version, unauthorized or
+uncertain registry responses, unsupported tools and mismatched dependency bytes.
+These simulations and actionlint validate code/wiring. They do not prove GitHub
+environment settings, npm ownership or OIDC exchange work.
+
+Any documentation/package-metadata/source change after J6 creates a new candidate.
+J6 evidence applies only to J6's recorded commits/digests. Re-run this complete
+graph on final commits/tarballs and retain the new manifests/platform results.
+Never label changed bytes publishable using old evidence. A passing Windows
+local run does not substitute for actual hosted Linux/macOS jobs.
+
+## Owner configuration — external, not performed by this repository
+
+Rechecked against [npm trusted publishers](https://docs.npmjs.com/trusted-publishers/),
+[GitHub secure use](https://docs.github.com/en/actions/reference/security/secure-use),
+[OIDC](https://docs.github.com/en/actions/concepts/security/openid-connect), and
+[deployment environments](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments)
+on **2026-10-23**. Recheck those live requirements before first publication:
+
+1. The owner confirmed the `@poppykit` scope and selected MIT/version 0.1.0.
+   Confirm the actual publishing account has package-name/maintainer rights and
+   the chosen version is unused. The complete LICENSE is in the package allowlist
+   and release notes describe this initial development candidate.
+   Confirm repository.url exactly matches the actual GitHub repository.
+2. Protect main, release tags, Actions files/scripts and candidate pins with
+   repository rules and review/CODEOWNERS appropriate to the actual team. Require
+   the complete verification result for the exact commit. Prevent unreviewed
+   workflow changes or tag replacement. Read-only PR permissions and trusted
+   publishing cannot enforce these owner settings themselves.
+3. Create environment `npm` in each package repository with required reviewers,
+   self-approval restrictions, protected release-tag rules and no admin bypass
+   where the repository plan supports them. Confirm feature availability; an
+   unprotected environment name alone provides no approval barrier. Add environment
+   variable `NPM_PUBLISH_ENABLED=true` only after setup/authorization. Missing
+   or false configuration fails the publisher's check.
+4. Configure each npm package's trusted publisher for GitHub owner `LMol-4`,
+   the corresponding `poppykit-client`, `poppykit-server` or `poppykit-cli`
+   repository, workflow filename **release.yml**, and environment **npm**.
+   Match spelling/case and the initiating workflow identity. verify.yml is a
+   reusable verifier, not the publishing workflow. Reassess identity if introducing
+   a reusable publisher or changing callers; workflow_call/dispatch identity has
+   documented caller nuances. This setup authorizes a workflow identity, not its
+   test results. The gate supplies the independent verification condition.
+5. npm currently requires npm >=11.5.1 and Node >=22.14.0 for trusted publishing;
+   this workflow uses Node24.12.0 and checks npm's version without upgrading it.
+   GitHub-hosted runners are supported; self-hosted runners are not supported for
+   this npm path. GitHub permissions must permit OIDC. No NODE_AUTH_TOKEN is set.
+   Do not silently fall back to a long-lived publish token when OIDC fails.
+6. Verify provenance requirements, repository visibility and package visibility
+   in the current npm documentation. Trusted publishing generates provenance
+   automatically for supported public packages/public repositories; explicit
+   --provenance must not be treated as proof without checking the registry record.
+   A private-source repository may need an owner-approved alternative or visibility
+   decision; do not claim provenance supported where it is not.
+7. Current npm publisher configurations require first successful use within two
+   days or expire; configure near the authorized release. npm supports up to ten
+   configurations, with separate direct-publish/staging/dist-tag permissions.
+   Grant only this workflow's required direct publication capability, review other
+   publishers/tokens and restrict alternative access according to owner policy.
+   Keep recovery access separate from the normal workflow.
+
+## First publication and bootstrap
+
+A new package may need first publication using authorized npm-owner authentication
+before package settings/trusted publishing are available. npm name availability
+has not been established by creating a GitHub repository. The owner must confirm
+the current bootstrap flow and explicitly authorize it. Do not place bootstrap
+tokens in PR workflows or temporarily make publication unconditional.
+
+Prepare a license/version-ready candidate, run the exact full verification graph,
+retain/download the unchanged manifest/tarball and verify its digest. If the first
+publication must be manual, an authorized owner uses their own current npm login/
+2FA or narrowly scoped supported bootstrap credential to publish those exact bytes,
+then removes temporary credentials and configures the trusted publisher. Record
+the resulting version/integrity/provenance. A dry run is not proof of bootstrap
+permissions or production OIDC authentication. Current 0.1.0 candidates have public-ready metadata, but publication still
+requires all exact-byte checks, owner settings and separate authorization.
+
+## Package order, existing versions and partial recovery
+
+Release by actual production dependencies: client and server are independent;
+either SDK can publish first. Publish the client before a CLI version requiring
+that exact client version. The CLI registry guard requires the published client's
+dist.integrity to match its tested candidate tarball. If it differs, stop and
+reconcile/retest the actual dependency; do not silently replace tested bytes.
+
+Before publishing, npm view must confirm that this package version is absent.
+Only a structured E404 is considered absent; auth/network/registry failures stop.
+An existing version stops publication even after an uncertain earlier response.
+Inspect npm's published version, integrity, provenance and intended dist-tag using
+read-only registry commands. Never overwrite or blindly republish. If the exact
+bytes already published, record that success and resume the remaining package's
+separate verified release. Multi-repository releases are not atomic. Do not unpublish
+a successful dependency as rollback. If correction is required, choose a new
+version, update dependent pins/lockfiles/release notes and verify a new candidate.
+
+This runbook does not authorize publication, tag pushes, package ownership changes,
+external settings, deployment or demo implementation.
+
+Candidate metadata is inspected with the archive basename and its directory as
+`cwd`. This avoids GNU tar interpreting a Windows drive colon as a remote archive;
+stderr is preserved in failure diagnostics. Negative checks exercise GNU tar on
+Windows with space/Unicode candidate paths and retain wrong/missing/changed bytes
+and fail-closed gate cases. Local success does not certify a future hosted run or
+any newly packed bytes.

package/SECURITY.md

@@ -0,0 +1,13 @@
+# Security reporting
+
+Do not put credentials, tokens, private keys, personal records or exploit details
+in a public issue. Use this repository's GitHub **Security → Report a vulnerability**
+when private reporting is enabled. If it is unavailable, request a private contact
+from the repository owner without disclosing the vulnerability publicly. The owner
+must enable/confirm that route before public release; no response SLA is promised.
+
+Include affected commit/version, a minimal reproduction using synthetic data,
+impact and the trust boundary involved. These unpublished draft packages have no
+released-version support window yet. Custom vaults, issuers, browser controllers,
+proxy routing and deployment policy remain operator responsibilities. Redaction
+and scoped authority do not isolate an unrestricted same-user program.

package/STORAGE.md

@@ -0,0 +1,99 @@
+# Persistence and recovery
+
+This unpublished package uses targeted storage contracts. Node 24.12.0
+or later is required. The optional `@poppykit/client/sqlite` entry point exports
+`SqliteAuthStore` and `SqliteConversationStore`; importing the client core does not
+load SQLite. `node:sqlite` is experimental in the tested Node 24.12.0 runtime.
+Consumers can implement `AuthStore` and `ConversationStore` using their own database.
+
+```ts
+import { SqliteAuthStore, SqliteConversationStore } from '@poppykit/client/sqlite';
+const authStore = new SqliteAuthStore('/private/path/auth.db');
+const conversationStore = new SqliteConversationStore('/private/path/messages.db');
+// Pass authStore to createClientAuth and conversationStore to createConversationClient.
+// Close both after all operations have finished.
+```
+
+Use one auth database per namespace/local user/client identity. The owner tuple is
+checked on every SDK auth read and mutation. Identities are keyed by the exact full
+issuer, connections by immutable IDs, operations by ID and callback state hash,
+cleanup by connection, and token slots by session/resource. Secret values are never
+stored in auth records: immutable references point to the host's `SecretStore`.
+Session Tokens remain in process memory. Conversation databases contain message
+bodies; operators must provide private storage and their required encryption.
+
+Auth selections load an identity or a connection aggregate (its grants, operations,
+and cleanup), never unrelated connections. Operation/callback selectors resolve the
+owning connection through indexes. `list` explicitly enumerates connections.
+Recovery pages nonterminal operation IDs in batches of 100, then rechecks each
+operation and its owner inside its transaction. `cleanup(before, limit)` removes
+only terminal, non-uncertain auth history; the limit is at most 1000. It does not
+erase grants, pending exchanges, uncertain results, or secrets.
+
+Transactions must serialize conflicting domain updates across processes, roll back
+on exceptions, reject asynchronous mutation callbacks and non-JSON persisted values,
+enforce unique keys, and return detached values. SQLite uses WAL, FULL synchronous
+commits and a bounded busy wait. It serializes writers; parallel writers are not a
+promise. The database file must be on a local filesystem that supports SQLite's
+locking; this is not a distributed database. Create adapters before starting work,
+and keep network/vault calls outside transaction callbacks.
+
+Conversation storage has separate prepare/get/settle operations and checkpoint
+compare-and-set. An outbound ID is unique per connection/full issuer, and also
+records its endpoint. Retry rejects an endpoint change before sending. Preparation
+returns the existing record instead of replacing content; terminal outcomes cannot
+be overwritten by a late sender. Checkpoints include endpoint, conversation and
+consumer. Receipts remain available for retries: the old `keepCompleted` deletion
+behavior is removed. J3 owns retention with preserved message identity and bounded
+payload cleanup; no automatic age-based deletion is currently performed.
+
+`MemoryConversationStore` from `@poppykit/client/memory` is non-durable and confined
+to one process. The SQLite adapters also accept `:memory:` for non-durable tests;
+each such adapter has its own database. Neither mode demonstrates process recovery.
+
+## Operation ownership
+
+Each active rotation or code exchange records a random execution owner, host name,
+and PID before dispatch. The default liveness check keeps other running local
+processes live; within this process it tracks actual active executions. Unknown
+remote hosts and permission errors are conservatively live. A new invocation cannot
+invalidate an active exchange just by starting recovery. A reused PID can delay
+recovery; it cannot authorize replay. Multi-host adapters must supply a trustworthy
+`ownerAlive` hook backed by their deployment's ownership/fencing mechanism. Returning
+false is an assertion of abandonment, not a request to cancel an active operation.
+
+Recovery rechecks phase/generation and liveness under the database transaction. A
+prepared abandoned rotation can release its claim; a dispatched exchange without a
+durably staged response becomes uncertain. A staged rotation can activate locally
+only if its connection/grant generations still match. Cancellation, disconnection,
+or another generation wins over late activation. No remote token exchange is replayed
+by recovery, and lease expiry would not prove that a request was never sent.
+
+The vault and remote issuer are outside the database transaction. Stage immutable
+secrets first, conditionally activate references, then remove superseded secrets.
+Vault failure or process death can leave an unreferenced staged secret; the host
+needs an orphan-secret sweep that respects active owners and a grace period. A lost
+remote rotation response remains uncertain. This adapter does not promise automatic
+recovery of a token that the issuer rotated but never delivered.
+
+## Development reset
+
+There is no automatic migration from old whole-state development stores. Stop all
+users of a disposable store, resolve uncertain remote outcomes, and explicitly move
+aside its database and WAL/SHM files and the matching host-managed secret namespace
+before creating a fresh store. Never reset live credentials by deleting a database
+behind a running process. Old stores are not silently deleted or reinterpreted.
+
+`tests/storage.test.mts` uses actual child processes, SQLite contention and forced
+termination. It covers rollback, durable prepare, live-owner recovery and an external
+synthetic effect followed by owner death. The latter becomes uncertain, not an
+exactly-once execution claim. Auth unit tests also retain staged-secret, generation,
+revocation-race and vault-failure coverage.
+
+## Conversation delivery lifetime
+
+See [DELIVERY.md](DELIVERY.md) for the retention table. Outbound records and
+checkpoints are retained until explicit local deletion; pending/uncertain retries
+must first be reconciled. Checkpoint acknowledgements use compare-and-set and do
+not acknowledge merely because a page or stream frame was read. Local deletion
+never deletes company history, revokes access or cancels accepted business work.

package/dist/auth/challenge.d.ts

@@ -0,0 +1,19 @@
+export declare function schemeChallenge(header: string | null, scheme: 'DPoP' | 'Bearer'): {
+    error?: string;
+    scope?: string;
+    extension?: string;
+    conversation_id?: string;
+} | undefined;
+export declare const dpopChallenge: (header: string | null) => {
+    error?: string;
+    scope?: string;
+    extension?: string;
+    conversation_id?: string;
+} | undefined;
+export interface AuthChallenge {
+    error?: string;
+    requiredScopes: string[];
+    extensions: string[];
+    conversationId?: string;
+}
+export declare function authChallenge(header: string | null, body?: unknown): AuthChallenge;

package/dist/auth/challenge.js

@@ -0,0 +1,68 @@
+// Reads the DPoP challenge from a WWW-Authenticate header (RFC 9110 11.6.1, spec 6); other schemes' params are ignored.
+const TOKEN = /[A-Za-z0-9!#$%&'*+.^_`|~-]+/y;
+export function schemeChallenge(header, scheme) {
+    if (!header)
+        return undefined;
+    let i = 0;
+    let current;
+    let found;
+    const skip = (chars) => { while (i < header.length && chars.test(header[i]))
+        i++; };
+    while (i < header.length) {
+        skip(/[\s,]/);
+        TOKEN.lastIndex = i;
+        const match = TOKEN.exec(header);
+        if (!match) {
+            i++;
+            continue;
+        }
+        i += match[0].length;
+        const afterToken = i;
+        skip(/\s/);
+        if (header[i] !== '=' || !current) {
+            if (header[i] === '=') {
+                i = afterToken;
+                skip(/[=\s]/);
+                continue;
+            } // token68 or stray param before any scheme
+            current = { scheme: match[0].toLowerCase(), params: {} };
+            if (current.scheme === scheme.toLowerCase())
+                found = current.params;
+            i = afterToken;
+            continue;
+        }
+        i++;
+        skip(/\s/);
+        let value = '';
+        if (header[i] === '"') {
+            i++;
+            while (i < header.length && header[i] !== '"') {
+                if (header[i] === '\\')
+                    i++;
+                value += header[i] ?? '';
+                i++;
+            }
+            i++;
+        }
+        else {
+            TOKEN.lastIndex = i;
+            value = TOKEN.exec(header)?.[0] ?? '';
+            i += value.length;
+        }
+        const name = match[0].toLowerCase();
+        if (current.scheme === scheme.toLowerCase() && ['error', 'scope', 'extension', 'conversation_id'].includes(name))
+            current.params[name] = value;
+    }
+    return found;
+}
+export const dpopChallenge = (header) => schemeChallenge(header, 'DPoP');
+// Combine independent detail channels: a sparse JSON error must not erase header scopes/extensions.
+export function authChallenge(header, body) {
+    const challenge = dpopChallenge(header), json = body && typeof body === 'object' && !Array.isArray(body) ? body : {};
+    const scopes = [challenge?.scope, json.scope].flatMap(value => typeof value === 'string' ? value.split(' ').filter(scope => /^[\x21\x23-\x5B\x5D-\x7E]+$/.test(scope)) : []);
+    const extensions = [challenge?.extension, json.extension].filter((value) => typeof value === 'string' && value.length <= 512 && /^(?:[A-Za-z0-9._-]+|(?:[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\.)+[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\/[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)*)$/.test(value));
+    const safe = new Set(['sign_in_required', 'insufficient_scope', 'invalid_token', 'invalid_dpop_proof', 'use_dpop_nonce', 'extension_required', 'rate_limited', 'invalid_scope']);
+    const error = [challenge?.error, json.error].find((value) => typeof value === 'string' && safe.has(value));
+    const conversationId = [json.conversation_id, challenge?.conversation_id].find((value) => typeof value === 'string' && value.length > 0 && value.length <= 256);
+    return { ...(error ? { error } : {}), requiredScopes: [...new Set(scopes)], extensions: [...new Set(extensions)], ...(conversationId ? { conversationId } : {}) };
+}