@jimhoyd/urlcode 0.4.0-alpha.1 → 0.4.0-alpha.2

package/dist/types/link-store.d.ts

@@ -1,130 +0,0 @@
-import type { LinkRecord } from './link-records.ts';
-import type { LogFn } from './types.ts';
-/** A stored link as the worker returns it. */
-export interface LinkRow extends LinkRecord {
-    collection: string;
-    code: string;
-    version: number;
-}
-export interface ListOptions {
-    limit?: number | undefined;
-    after?: string | undefined;
-}
-export interface AuditIdentity {
-    actor?: string | undefined;
-    requestId?: string | undefined;
-}
-export interface ExportHeader {
-    format: string;
-    schemaVersion: number;
-    applicationId: number;
-    collection: string | null;
-    revision: number;
-    records: number;
-    generatedAt: string;
-}
-export interface ExportPageOptions {
-    afterCollection?: string | undefined;
-    afterCode?: string | undefined;
-    limit?: number | undefined;
-}
-export interface ExportOptions {
-    collection?: string | undefined;
-    pageSize?: number | undefined;
-    deadlineMs?: number | undefined;
-}
-export interface ExportHandlers {
-    onHeader?: ((header: ExportHeader) => unknown) | undefined;
-    onRecords?: ((records: LinkRow[]) => unknown) | undefined;
-}
-export interface ExportSummary extends ExportHeader {
-    exported: number;
-}
-export interface PoolStats {
-    connections: number;
-    healthyConnections: number;
-    limit: number;
-    inFlight: number;
-    completed: number;
-    failed: number;
-    rejected: number;
-    durationMs: number;
-}
-export interface LinkStoreStats {
-    closed: boolean;
-    exporting: boolean;
-    read: PoolStats;
-    write: PoolStats;
-}
-export interface LinkStoreWorkerData {
-    file: string;
-    readOnly: boolean;
-}
-export type LinkStoreOperation = 'get' | 'list' | 'create' | 'update' | 'delete' | 'exportBegin' | 'exportPage' | 'exportEnd' | 'close';
-export interface LinkStoreArgs extends ListOptions, ExportPageOptions {
-    collection?: string | undefined;
-    code?: unknown;
-    data?: unknown;
-    expectedVersion?: unknown;
-    audit?: AuditIdentity | undefined;
-}
-export interface LinkStoreCommand {
-    id: number;
-    operation: LinkStoreOperation;
-    args: LinkStoreArgs;
-}
-export type LinkStoreReply = {
-    ready: true;
-} | {
-    failed: true;
-} | {
-    id: number;
-    value: unknown;
-} | {
-    id: number;
-    error: {
-        status: number;
-        message: string;
-    };
-};
-/** One worker-backed SQLite connection. */
-export interface LinkConnection {
-    readonly healthy: boolean;
-    get(collection: string, code: string): Promise<LinkRow | null>;
-    list(collection: string, options?: ListOptions): Promise<LinkRow[]>;
-    exportBegin(options?: {
-        collection?: string | undefined;
-    }): Promise<ExportHeader>;
-    exportPage(options?: ExportPageOptions): Promise<LinkRow[]>;
-    exportEnd(): Promise<boolean>;
-    create(collection: string, data: unknown, code?: unknown, audit?: AuditIdentity | undefined): Promise<LinkRow>;
-    update(collection: string, code: string, data: unknown, expectedVersion: unknown, audit?: AuditIdentity | undefined): Promise<LinkRow>;
-    delete(collection: string, code: string, expectedVersion: unknown, audit?: AuditIdentity | undefined): Promise<boolean>;
-    close(): Promise<void>;
-}
-/** The pooled store openLinkStore returns. */
-export interface LinkStore {
-    readonly readHealthy: boolean;
-    readonly writeHealthy: boolean;
-    readonly healthy: boolean;
-    readonly atomicAudit: true;
-    stats(): LinkStoreStats;
-    exportSnapshot(options?: ExportOptions, handlers?: ExportHandlers): Promise<ExportSummary>;
-    get(collection: string, code: string): Promise<LinkRow | null>;
-    list(collection: string, options?: ListOptions): Promise<LinkRow[]>;
-    create(collection: string, data: unknown, code?: unknown, audit?: AuditIdentity | undefined): Promise<LinkRow>;
-    update(collection: string, code: string, data: unknown, expectedVersion: unknown, audit?: AuditIdentity | undefined): Promise<LinkRow>;
-    delete(collection: string, code: string, expectedVersion: unknown, audit?: AuditIdentity | undefined): Promise<boolean>;
-    close(): Promise<void>;
-}
-export interface LinkStoreOptions {
-    file?: string | undefined;
-    project?: string | undefined;
-    readOnly?: boolean | undefined;
-    readers?: number | undefined;
-    maxReads?: number | undefined;
-    maxWrites?: number | undefined;
-    log?: LogFn | undefined;
-}
-export declare function outsideProject(file: unknown, project: string): Promise<string>;
-export declare function openLinkStore({ file, project, readOnly, readers, maxReads, maxWrites, log }?: LinkStoreOptions): Promise<LinkStore>;

package/dist/types/management-policy.d.ts

@@ -1,8 +0,0 @@
-/** A credential from the operator's management policy file, once it authenticated a request. */
-export interface ManagementPrincipal {
-    id: string;
-    collections: string[];
-    actions: string[];
-}
-export type ManagementAuthorizer = (token: string) => Promise<ManagementPrincipal | undefined>;
-export declare function managementPolicy(file: unknown, project: string): Promise<ManagementAuthorizer>;

package/dist/types/sqlite-version.d.ts

@@ -1 +0,0 @@
-export declare function supportsConcurrentWal(version: unknown): boolean;

package/docs/DYNAMIC-LINKS.md

@@ -1,61 +0,0 @@
-# Dynamic short links without reloads
-
-Define a stable route once and create, update and delete short-code records
-while `serve` keeps running, from optional SQLite storage on one host. Each
-section below lives on its own page; the headings here keep existing links working.
-
-## Node build requirement
-
-SQLite 3.51.3+ (or 3.50.7 / 3.44.6) bundled with Node; `urlcode doctor` reports it. Read [setup](links/setup.md#node-build-requirement).
-
-## Behavior in YAML, data outside Git
-
-The `link` handler and the operator store binding. Read [setup](links/setup.md#behavior-in-yaml-data-outside-git).
-
-## Run the included example
-
-`links init`, `links create` and `serve --link-store` against a private data directory. Read [setup](links/setup.md#run-the-included-example).
-
-## Update, disable, expire, list and delete
-
-`links get/list/update/delete` and the optimistic version rules. Read [cli](links/cli.md#update-disable-expire-list-and-delete).
-
-## Consistent operator export and restore
-
-`links export` holds one read transaction; `links import` refuses occupied collections. Read [cli](links/cli.md#consistent-operator-export-and-restore).
-
-## A separate authenticated management API
-
-`links api`: bearer token, endpoints, status codes and scope. Read [management-api](links/management-api.md#a-separate-authenticated-management-api).
-
-## Persistence, bounds and recovery
-
-Pools, deadlines, worker replacement with backoff, record caps and backups. Read [limits](links/limits.md#persistence-bounds-and-recovery).
-
-## Middleware, sandbox and tests
-
-What guest code can and cannot see; fixtures for `test` and `audit`. Read [setup](links/setup.md#middleware-sandbox-and-tests).
-
-## Opt-in completed-redirect events
-
-The `linkEvents` observer: outcomes, redaction, bounded delivery. Read [limits](links/limits.md#opt-in-completed-redirect-events).
-
-## Shutdown and management defaults
-
-Loopback defaults, drain on close, unknown outcomes after a timeout. Read [pools](links/pools.md#shutdown-and-management-defaults).
-
-## Explicit project opt-in
-
-`dynamicLinks: true` in the entry file only; what enabling changes. Read [setup](links/setup.md#explicit-project-opt-in).
-
-## Separate reader and writer pools
-
-`--link-readers`, `--link-read-limit`, `--link-write-limit` and `stats()`. Read [pools](links/pools.md#separate-reader-and-writer-pools).
-
-## Management HTTP and audit safeguards
-
-Admission, socket timeout and `management_request` events. Read [management-api](links/management-api.md#management-http-and-audit-safeguards).
-
-## Management hardening baseline
-
-Loopback only, `--auth-file` credentials, durable audit rows. Read [management-api](links/management-api.md#management-hardening-baseline).

package/docs/MANAGEMENT-SECURITY.md

@@ -1,82 +0,0 @@
-# Private management and durable mutation audit
-
-Management binds only `127.0.0.1` or `::1`. Use an authenticated private tunnel
-(e.g. SSH/VPN with loopback forwarding); never publish its port through a public
-proxy or container port mapping. This is operator management, not an end-user
-account service. Browser Origin requests remain rejected.
-
-## Individual credentials
-
-Use `urlcode links api --project ./my-links --store /operator/links.sqlite
---auth-file /operator/management.json --host 127.0.0.1 --port 3001` (one line).
-The policy is operator-owned, outside the application, at most 64 KiB and mode
-600 on POSIX. Protect its parent directory and apply equivalent Windows ACLs.
-It is not YAML and must never be placed in the application or Git.
-
-Generate each token with `node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"`
-on a trusted operator machine. Deliver it through your secret manager. Hash the
-raw token using SHA-256 without a newline; the server expects `Authorization:
-Bearer <token>`. Tokens must contain 43–256 base64url characters. Never use a
-human password as a token. This synthetic policy illustrates the shape; replace
-the hash with the real token hash and choose a short operational expiry:
-
-```json
-{
-  "version": 1,
-  "credentials": [{
-    "id": "operator-alice",
-    "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
-    "expires": "2026-10-01T00:00:00Z",
-    "collections": ["links"],
-    "actions": ["get", "list", "create", "update", "delete"]
-  }]
-}
-```
-
-At most 128 credentials; unique IDs and hashes; explicit collection and action
-allowlists with no wildcards. Readers should receive only `get` and `list`.
-An expired, removed or `"revoked": true` credential gets 401; a valid credential
-outside its scope gets 403. The entire policy is validated on every authenticated
-request. Malformed/unreadable policy fails closed with 503, without retaining an
-old permissive copy. Write a replacement file with mode 600 and atomically rename
-it over the policy. No restart is needed. Requests already authorized may finish;
-revocation does not cancel an in-flight transaction. Credential administration is
-an operator filesystem action, never exposed through this HTTP API.
-
-Legacy `--token-file` remains available for local compatibility, with full access
-to that listener's collection and actor `legacy-shared`. Prefer `--auth-file` for
-attribution, expiry and revocation. They are mutually exclusive. These bearer
-credentials do not establish verified human identity, MFA, SSO or session login.
-Host administrators and custom embedding code remain trusted operators.
-
-## Audit durability and recovery
-
-The built-in SQLite writer creates an additive `urlcode_link_audit` table when
-opening a store. Every successful create/update/delete (including CLI and embedded
-store calls) records revision, UTC timestamp, actor, request ID, collection,
-action and SHA-256 of the short code in the **same transaction** as the mutation.
-The default local CLI actor is `local-operator`. Scoped HTTP management requires
-an adapter explicitly declaring atomic audit support; the built-in store provides it.
-
-An audit insert failure rolls back both mutation and revision. Conditional-write
-conflicts and rejected requests produce no successful-mutation row. HTTP request
-logs still describe failed/aborted requests and remain best effort. A client timeout
-may follow a committed transaction: reconcile the revision and request ID before
-retrying. A lost HTTP reply is not evidence that the transaction was rolled back.
-
-Inspect the journal with an operator-only SQLite client, for example:
-
-```sql
-SELECT revision, timestamp, actor, request_id, collection, action, code_sha256
-FROM urlcode_link_audit WHERE revision > 0 ORDER BY revision LIMIT 100;
-```
-
-No token, URL, request body or raw short code is stored in the journal. Code hashes
-are correlatable and guessable for short codes; restrict access accordingly.
-This is a durable local transaction journal, **not tamper-evident external storage**.
-An administrator with database access can change it. Export ordered revisions to
-your protected collector/backup system and monitor lag, gaps and disk/WAL growth.
-There is no automatic pruning: define retention and verify archival before any
-operator purge. Keep audit records in backups. User_version remains 1 because
-this table is additive; older readers work, but older writers do not emit audit
-rows. Never roll a management writer back to an unaudited revision.

package/docs/links/cli.md

@@ -1,110 +0,0 @@
-# Dynamic links: CLI: create, update, export and restore
-
-Part of [dynamic links](../DYNAMIC-LINKS.md), which indexes every page.
-
-## Update, disable, expire, list and delete
-
-```sh
-urlcode links get --store /absolute/links.sqlite --code demo
-urlcode links list --store /absolute/links.sqlite --limit 100
-urlcode links list --store /absolute/links.sqlite --limit 100 --after last-code
-urlcode links update --store /absolute/links.sqlite --code demo \
-  --if-version 1 --destination https://example.com/new --enabled false
-urlcode links delete --store /absolute/links.sqlite --code demo --if-version 2
-```
-
-Replace illustrative versions with the actual returned `version`. Update is a
-**full replacement**: omitted status becomes 302, enabled becomes true, and expiry
-becomes null. Use `--status 307` or `--expires 2030-01-01T00:00:00Z` as needed.
-Allowed status codes match ordinary redirects. Disabled/expired records remain
-stored and reserve the code until explicitly deleted.
-
-Create is insert-only: an existing code returns conflict, never an overwrite.
-Updates/deletes require a matching positive version. Every mutation uses a
-transaction; revisions advance globally within that database, including deletion,
-so a stale edit cannot silently affect a deleted-and-recreated code. Competing
-writers receive a conflict. Read the latest record before making a new decision;
-do not blindly retry a stale update. Listing is ordered by code, at most 100 per
-page, within one collection. Pagination is not a snapshot across concurrent writes.
-
-CLI commands print record data intentionally; treat output as operational data.
-Do not store secrets in destinations or capture output into public logs.
-`urlcode add` remains the separate command for adding a Git/YAML-defined redirect.
-
-## Consistent operator export and restore
-
-Listing pages one after another is not a snapshot: inserts, updates and deletes
-between pages can produce a logically inconsistent copy. `links export` instead
-holds one SQLite read transaction for the whole export, so every record it writes
-comes from a single point in time.
-
-```sh
-umask 077
-urlcode links export --store /absolute/links.sqlite > /absolute/backups/links-export.ndjson
-urlcode links import --store /absolute/restored.sqlite --input /absolute/backups/links-export.ndjson
-```
-
-Export is an operator command on the operator's own database. It is not reachable
-from the public redirect server, from route YAML, from guest function code or from
-the management HTTP API, and it grants guest code no storage capability. The
-output is operational data: write it somewhere only operators can read, keep it out
-of the project, Git and build artifacts, and treat it like the database itself.
-
-**Consistency contract.** The export reflects the database exactly as of the moment
-the snapshot is pinned, which is the first read after the transaction opens. Writers
-are never blocked and keep committing; none of their later commits appear in the
-export, and no record appears twice or is skipped. The header line carries
-`format`, `schemaVersion`, `applicationId`, the store `revision` at that instant and
-`generatedAt`, so a restored copy can be identified and ordered against others. This
-is a consistent logical copy, not a point-in-time recovery system: it has no
-continuous log and cannot reconstruct a moment between two exports.
-
-**Contents.** Every record in the store, or in one `--collection`, including
-enabled, disabled and expired records, with `collection`, `code`, `url`, `status`,
-`enabled`, `expires` and `version`. Disabled and expired records are exported
-because they still reserve their codes. The output is NDJSON: a
-`link-export-begin` header line, one `{"record": {...}}` line per record ordered by
-collection and code, and a `link-export-complete` line carrying the record count
-and a SHA-256 digest over every preceding line. A stream without that final line is
-truncated, and `links import` rejects it.
-
-**Restore semantics.** `links import` replays the records into the target store and
-refuses to touch a collection that already holds records, so a restore never
-overwrites live data. It verifies the format, schema version, store identity, record
-count and digest before it commits the last record. Codes, destinations, statuses,
-enabled flags and expiries are restored exactly. **Versions are not.** The target
-assigns its own revisions, which is why the report sets `versionsReassigned: true`:
-management ETags taken against the exported database are stale after a restore, so
-discard them and re-read records before the next conditional write, exactly as after
-restoring an older database file.
-
-**Audit journal.** The export carries records only. The mutation audit journal stays
-in the source database and is not part of an export, so a store restored from one
-starts a fresh journal covering only mutations made after the restore. Keep the
-journal by backing up the database file itself, as described under *Persistence,
-bounds and recovery*; that file backup, not the export, is the archival copy of who
-changed what. See [management security](../MANAGEMENT-SECURITY.md) for retention.
-
-**Bounds.** One export runs at a time per store and a second is rejected with 409.
-It pins exactly one reader connection and holds that reader's admission for its whole
-life, so it can never exceed the pool's read budget or starve redirects of every
-reader — run it against a management store or size `--link-readers` accordingly.
-Pages are at most 100 records (`--page-size`), each page carries the usual
-five-second operation deadline, and the export as a whole has a 60-second default
-deadline after which it fails and releases the reader. A consumer that fails or a
-process that stops ends the read transaction rather than leaving it open. Because
-the transaction pins a WAL read mark, a long export delays WAL checkpointing: keep
-exports short and do not leave one running against a busy store.
-
-Embedders call the same mechanism directly:
-
-```js
-await store.exportSnapshot({collection: 'links', pageSize: 100, deadlineMs: 60000}, {
-  onHeader: header => sink.write(header),
-  onRecords: records => sink.write(records),
-});
-```
-
-`onRecords` is awaited, so a slow sink applies backpressure to the export instead of
-buffering the store in memory; anything it throws aborts the export and releases the
-reader. `stats()` reports `exporting` while one is in flight.

package/docs/links/limits.md

@@ -1,175 +0,0 @@
-# Dynamic links: Persistence, bounds, recovery and events
-
-Part of [dynamic links](../DYNAMIC-LINKS.md), which indexes every page.
-
-## Persistence, bounds and recovery
-
-SQLite operations use separate reader and writer pools, outside the HTTP event
-loop and function workers. Default: two read-only worker connections plus one
-writer for writable stores; public serving opens readers only. Reads and writes
-have independent 32-operation admission limits and 5-second deadlines including
-waiting. Lock wait is one second. Excess work returns 503. Failed connections
-are excluded from selection and readiness degrades; surviving readers can still
-serve requests. Plain YAML redirects remain independent.
-
-Startup and established-worker failures recover differently.
-
-* **Startup failure.** A connection that never reports ready is terminated and its
-  error is returned to the caller: `openLinkStore` rejects and activation fails
-  closed. Nothing is retried behind the operator's back, so a `serve` or `links api`
-  process that cannot open the store does not start, and a reload that cannot open
-  it keeps the last-good runtime.
-* **Established-worker failure.** A connection that had been serving and then
-  errors, exits or misses an operation deadline is replaced automatically.
-  In-flight operations on it reject with 503, the connection is marked unhealthy
-  and excluded from selection, and a replacement worker is launched after an
-  exponential backoff from 250 ms up to 30 seconds. Each attempt emits a
-  `link_store_worker` event with `status: "restarting"`, the attempt number and the
-  delay; a replacement that serves an operation resets the backoff, and one that
-  starts but dies on every operation keeps backing off instead of spinning. Close
-  cancels a pending replacement.
-
-While a pool member is down the pool is degraded, not off: `readHealthy`,
-`writeHealthy` and `healthy` report false and readiness degrades, but surviving
-readers keep answering and a recovered writer resumes accepting mutations with no
-operator action. Records live on disk, so a replaced connection loses no committed
-data.
-
-Restart the process when recovery cannot help: an unsuitable Node/SQLite build,
-missing or invalid revision metadata, an incompatible schema, a store file that was
-replaced, moved or symlinked under a running connection, or a host-level fault such
-as a full or read-only disk. Those fail activation rather than reconnecting, and
-the replacement worker will keep failing until the underlying cause is fixed.
-
-Automatic connection recovery does not make writes idempotent. A mutation whose
-reply was lost to a worker failure or deadline may still have committed, and the
-records it touched carry versions that advance globally. Callers must therefore
-re-read the record and decide again instead of blindly retrying a write; the
-optimistic-version rules under *Update, disable, expire, list and delete* apply
-unchanged. Recovery behavior is covered by the `acknowledged writes survive abrupt
-writer exit and pagination retains records`, `a blocked writer does not occupy read
-connections and recovers after lock release` and `stores with missing revision
-metadata fail activation` cases in `test/links.test.ts`.
-
-The initial store has a 100,000-record cap across collections and an 8,192-byte
-normalized destination limit. WAL + FULL synchronous commits provide transactional
-persistence subject to the disk/filesystem's guarantees. The format has an
-application identifier and schema version; incompatible databases fail activation.
-Use trusted local storage and a protected parent directory. Do not replace,
-symlink or move an open database or its WAL/SHM files. The database and token must
-be outside the project; keep them outside public directories, Git and artifacts.
-
-An acknowledged mutation is committed. If a caller loses the response or receives
-a timeout, the write may nevertheless have committed: inspect state before retry.
-For retryable creation, choose a stable code and resolve conflicts; automatic
-code generation cannot give exactly-once semantics after a lost response.
-
-`links export` gives a consistent logical copy of the records while the store keeps
-serving; it does not replace a file backup, which is what preserves the audit
-journal and the exact record versions. For offline backups, stop management writers and all readers, then copy the
-database together with any remaining WAL file as one consistent stopped set,
-preserving their matching basenames. Restore into a separate private directory
-while no connection is open. Do not discard a WAL just because the app stopped.
-For online backups, use SQLite-aware tooling rather than copying only the live
-main file. SQLite's [WAL documentation](https://www.sqlite.org/wal.html) explains why
-committed state may still be in the WAL. Test restores on a separate closed store.
-Restoring an older database also restores older record versions: discard old
-management ETags and re-read records after restore. This is not a replication or
-point-in-time recovery system. Define retention, RPO/RTO and disk limits yourself.
-
-Multiple same-host processes can share the local file; a distributed deployment
-needs another adapter. The trusted embedding API accepts
-`linkStores: {links: adapter}` where `get(collection, code)` resolves to null or a
-record with url/status/enabled/expires. The caller owns adapter shutdown and must
-provide bounded operations, validation and consistency. Optional `healthy=false`
-makes readiness fail. `openLinkStore` provides the built-in implementation plus
-create/update/delete/list/exportSnapshot/close methods. Adapter code is operator code, never
-loaded from route YAML. No remote provider adapter ships in this release.
-
-## Opt-in completed-redirect events
-
-Default request logs stay minimal: they carry status and timing, and with
-`--request-log detailed` the method and the configured route pattern. They never
-carry a short code or a request target. Counting store lookups is not a substitute
-either, because a lookup cannot tell a completed redirect from a HEAD probe, an
-error or a client that disconnected.
-
-A trusted operator embedding the runtime can instead enable a post-response
-observer. It is explicitly enabled in operator code, off by default, and there is no
-`serve` flag and no YAML setting for it: route YAML cannot name a callback, and no
-untrusted code is ever loaded as one.
-
-```js
-import {startServer} from '@jimhoyd/urlcode';
-
-await startServer({
-  project: './links',
-  linkStore: {collection: 'links', file: '/absolute/links.sqlite'},
-  linkEvents: {
-    observe: event => collector.record(event),  // operator code, awaited off the request path
-    includeCode: false,   // set true to disclose the short code to this collector
-    maxQueue: 256,        // 1–4096 events; excess is dropped and counted
-    timeoutMs: 1000,      // 1–10000 ms budget per observer call
-  },
-});
-```
-
-In TypeScript the collector's argument is `LinkEvent` and the option block is
-`LinkObserverOptions`, both exported from `urlcode` beside `LinkStore`,
-`LinkRow`, `LinkStoreOptions`, `LinkApi` and `LinkApiOptions`; the declarations
-ship with the package:
-
-```ts
-import { startServer, type LinkEvent, type LinkObserverOptions } from '@jimhoyd/urlcode';
-
-const linkEvents: LinkObserverOptions = {
-  observe: (event: LinkEvent) => collector.record(event),  // event.code is null for an invalid code
-  includeCode: false,
-};
-await startServer({ project: './links', linkStore: { collection: 'links', file: '/absolute/links.sqlite' }, linkEvents });
-```
-
-Each event is `{event: 'link_request', requestId, collection, route, method, status,
-outcome, durationMs}`, plus `code` only when `includeCode` is true. `route` is the
-configured route pattern, never the request target. Nothing else from the request is
-included: no token, destination URL, query string, headers, body, cookie or client
-IP address, and no stored record. Only stored-link routes produce events; a plain
-YAML redirect never does. Disclosing a short code identifies a link, so treat a
-collector that receives one as holding operational data and keep it off public logs.
-
-| `outcome` | Meaning |
-|---|---|
-| `completed` | The redirect response finished. With `method: "GET"` this is the closest thing to a click; `HEAD` is a probe, not a click |
-| `aborted` | A redirect was produced but the response never finished, because the peer disconnected |
-| `missing` | No record for that code |
-| `disabled` | The record exists but is disabled |
-| `expired` | The record exists but its expiry has passed |
-| `invalid_code` | The code failed route input validation |
-| `invalid_record` | The stored record failed validation |
-| `unavailable` | The store was unavailable or over its admission budget |
-
-Nothing here is a human click count. Bots, prefetchers, proxies and repeat requests
-all produce `completed` events, the runtime does not deduplicate, and browser and
-proxy caches mean a real navigation may produce no request at all. Do the
-interpretation in your own collector.
-
-**The observer cannot affect a redirect.** Events are enqueued after the response
-finishes or the connection closes, never before, so an observer cannot delay,
-rewrite or fail a redirect. Delivery is sequential and bounded: at most `maxQueue`
-events are held, each call gets `timeoutMs` and a slow or hung collector is
-abandoned rather than allowed to pin the queue, and a call that throws is counted
-instead of propagated. Drops and failures are counted, reported through
-`link_observer` events on the normal log and readable at any time through
-`app.linkEventStats()` as `{queued, delivered, dropped, failed, timedOut, closed}`.
-An overloaded collector loses events, by design, instead of growing memory.
-
-Shutdown closes the observer after the server's connections are gone, drains what
-was already accepted within one bounded deadline, drops the rest and emits a final
-`link_observer` event with `status: "closed"` and those totals. Events are
-best-effort operational signals, not durable analytics or an audit record: the
-durable, atomic record of mutations remains the store's audit journal.
-
-Tests cover GET and HEAD, completed and aborted responses, missing, disabled and
-expired records, default redaction and opt-in code disclosure, a failing collector,
-a hung collector hitting its budget, queue overflow with counted drops, and drain on
-shutdown.

package/docs/links/management-api.md

@@ -1,80 +0,0 @@
-# Dynamic links: The management API
-
-Part of [dynamic links](../DYNAMIC-LINKS.md), which indexes every page.
-
-## A separate authenticated management API
-
-For a web product, your trusted backend calls the management API after applying
-its own user authentication, authorization, quotas and abuse rules. The API is an
-operator interface, not a public anonymous link-creation endpoint. Never put its
-shared token in browser JavaScript. It is not available on the public route server.
-
-Generate a private token file outside the application (POSIX-compatible Node example):
-
-```sh
-node --input-type=module -e 'import {writeFileSync} from "node:fs"; import {randomBytes} from "node:crypto"; writeFileSync(process.argv[1],randomBytes(32).toString("base64url"),{mode:0o600,flag:"wx"})' /absolute/link-admin.token
-urlcode links api --store /absolute/links.sqlite --collection links \
-  --token-file /absolute/link-admin.token --host 127.0.0.1 --port 3001
-```
-
-Use a securely generated token, at least 43 base64url characters. File permissions
-must exclude group/other access on POSIX; protect Windows files with operator ACLs.
-The API reads the token at startup; rotate by replacing it and restarting this
-management process. This does not require restarting public resolution.
-
-Every request needs `Authorization: Bearer <token>`. Authenticate before body
-processing. Use application/json for POST/PUT, with no compression; max body is
-16 KiB. Browser Origin-bearing requests are rejected. No CORS, cookies, user
-accounts, per-user scopes, JWT system or automatic rate limiter is provided.
-Keep it on a private network/loopback behind authenticated TLS ingress as needed.
-If changing `--host`, protect it before exposing it; no built-in HTTPS exists.
-
-| Request | Result |
-|---|---|
-| `POST /v1/links` with `{ "code": "demo", "url": "https://example.com/demo" }` | 201 with record and ETag; code optional |
-| `GET /v1/links/demo` | 200 with record and ETag, or 404 |
-| `GET /v1/links?limit=100&after=demo` | `{items, nextAfter}`; nextAfter null on a short page |
-| `PUT /v1/links/demo`, `If-Match: "VERSION"`, complete record fields | Replace and return new record/ETag |
-| `DELETE /v1/links/demo`, `If-Match: "VERSION"` | 204 |
-
-POST accepts optional `code` plus `url`, optional `status`, `enabled`, `expires`.
-PUT accepts the same record fields except code, which is immutable. `expires`
-may be null. Responses include collection, code, url, status, enabled, expires,
-version. Missing precondition: 428; stale version or duplicate code: 409;
-invalid input: 400; authentication failure: 401; unsupported media: 415;
-record limit: 507; store failure/capacity: 503. Error messages omit credentials,
-submitted URLs and SQL details. A full page can return a cursor even when the
-next page will be empty. No bulk mutation API is implemented, and the management
-API exposes no export: sequential list pages are not a snapshot, so use the
-operator `links export` command above for a consistent copy.
-
-A token authorizes its configured collection, not all collections. There are no
-per-end-user permissions: those belong to your backend. The API can also list
-inactive records for management. The public `/r/{code}` route never exposes
-management JSON, token files or a mutation endpoint.
-
-## Management HTTP and audit safeguards
-
-The private API admits up to 32 in-flight HTTP requests through response finish
-or disconnect, returning 503 on overload. A 10-second socket inactivity timeout
-closes stalled peers; this is not a total response deadline. The embedding API
-accepts `maxInFlightRequests` (1–64) and `socketTimeoutMs` (100–60,000). Existing
-connection/body/header and database admission limits still apply. Noncanonical
-dot-segment/backslash path normalization is rejected.
-
-JSON `management_request` events go to stdout by default and include timestamp,
-request ID, collection, action, authentication result, status and finish/abort
-outcome. No token, code, destination, URL, headers or body is logged. Embedders
-can supply `log(event)`; failed sinks cannot crash request handling. These are
-best-effort operational events, not durable per-actor audit records. Aborted
-mutations may have committed: re-read state before retrying. See the
-[security review](../SECURITY-AUDIT.md) for remaining controls.
-
-## Management hardening baseline
-
-Management is now restricted to literal loopback addresses. Prefer `--auth-file`
-for individual expiring, revocable credentials with collection/action scopes.
-Every successful built-in store mutation has an atomic, durable SQLite audit row;
-HTTP request logs remain best effort. See [management security](../MANAGEMENT-SECURITY.md)
-for policy examples, compatibility, archival and rollback requirements, and
-[operational proof](../OPERATIONAL-PROOF.md) for executable recovery drills.