@haverstack/server 0.8.0 → 0.9.0

package/dist/middleware/errors.js

@@ -0,0 +1,64 @@
+import { StackPermissionError, StackNotFoundError } from '@haverstack/core';
+import { serializeError } from '@haverstack/wire-types';
+/**
+ * Central error handler. `serializeError()` covers every core `StackError`
+ * (thrown directly by routes or surfaced from `Stack`/`ScopedStack`) with
+ * the wire-format's typed `{ error: { code, message } }` body. Anything
+ * else is an unanticipated bug: log it and return a bodyless 500 rather
+ * than guessing at a taxonomy it doesn't belong to.
+ *
+ * `stack` is the unscoped root Stack, used only to probe existence for the
+ * refusal log below — never to read content or bypass a permission check
+ * for the response itself.
+ */
+export function errorMiddleware(logger, stack) {
+    return async (err, c) => {
+        const wire = serializeError(err);
+        if (wire) {
+            // A denial with a resolved auth is a verified DID that lacked the
+            // grant, which docs/spec/identity.md asks be logged. Anonymous
+            // denials are bodyless 401s from wireError() and never reach here.
+            const auth = c.get('auth');
+            if (err instanceof StackPermissionError && auth) {
+                logger.warn({
+                    requestId: c.get('requestId'),
+                    principalId: auth.principalId,
+                    subjectId: auth.subjectId,
+                }, 'Denied a verified requester');
+            }
+            // On the wire a refused record is indistinguishable from a missing
+            // one (docs/spec/wire-format.md § Server implementation checklist),
+            // but the operator is not the adversary: an unscoped probe, on a path
+            // already failing, recovers the distinction for the log alone. Debug
+            // rather than warn — this is the sharing graph, which the spec asks
+            // stay out of a general-purpose aggregator by default.
+            if (err instanceof StackNotFoundError && auth) {
+                const recordId = c.req.param('id');
+                if (recordId) {
+                    const existing = await stack.get(recordId);
+                    logger.debug({
+                        requestId: c.get('requestId'),
+                        principalId: auth.principalId,
+                        subjectId: auth.subjectId,
+                        recordId,
+                        existed: existing !== null,
+                        // Always 'read': ScopedStack collapses to StackNotFoundError
+                        // exactly when canRead() is false, whatever verb was asked.
+                        check: 'read',
+                    }, 'Refused a verified requester a 404');
+                }
+            }
+            // A 401 or 403 to an anonymous caller would confirm the record
+            // exists to someone who presented no credential, so a private record
+            // and a missing one answer alike. `Bearer` (RFC 6750 §3) — not the
+            // `did-challenge` exchange discovery advertises for obtaining a
+            // token — keeps the login prompt reachable without reopening that.
+            if (wire.status === 404 && !auth)
+                c.header('WWW-Authenticate', 'Bearer');
+            return c.json(wire.body, wire.status);
+        }
+        logger.error({ err, requestId: c.get('requestId') }, 'Unhandled request error');
+        return c.json({ error: { code: 'internal', message: 'Internal server error' } }, 500);
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/middleware/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/middleware/errors.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAc,MAAM,kBAAkB,CAAC;AAExF,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,KAAY;IAC1D,OAAO,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE;QACtB,MAAM,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,IAAI,EAAE,CAAC;YACT,kEAAkE;YAClE,+DAA+D;YAC/D,mEAAmE;YACnE,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC3B,IAAI,GAAG,YAAY,oBAAoB,IAAI,IAAI,EAAE,CAAC;gBAChD,MAAM,CAAC,IAAI,CACT;oBACE,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC;oBAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;oBAC7B,SAAS,EAAE,IAAI,CAAC,SAAS;iBAC1B,EACD,6BAA6B,CAC9B,CAAC;YACJ,CAAC;YACD,mEAAmE;YACnE,oEAAoE;YACpE,sEAAsE;YACtE,qEAAqE;YACrE,oEAAoE;YACpE,uDAAuD;YACvD,IAAI,GAAG,YAAY,kBAAkB,IAAI,IAAI,EAAE,CAAC;gBAC9C,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBACnC,IAAI,QAAQ,EAAE,CAAC;oBACb,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;oBAC3C,MAAM,CAAC,KAAK,CACV;wBACE,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC;wBAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;wBAC7B,SAAS,EAAE,IAAI,CAAC,SAAS;wBACzB,QAAQ;wBACR,OAAO,EAAE,QAAQ,KAAK,IAAI;wBAC1B,6DAA6D;wBAC7D,4DAA4D;wBAC5D,KAAK,EAAE,MAAM;qBACd,EACD,oCAAoC,CACrC,CAAC;gBACJ,CAAC;YACH,CAAC;YACD,+DAA+D;YAC/D,qEAAqE;YACrE,mEAAmE;YACnE,gEAAgE;YAChE,mEAAmE;YACnE,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI;gBAAE,CAAC,CAAC,MAAM,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAC;YACzE,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAA8B,CAAC,CAAC;QAChE,CAAC;QACD,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,EAAE,yBAAyB,CAAC,CAAC;QAChF,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,uBAAuB,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;IACxF,CAAC,CAAC;AACJ,CAAC"}

package/dist/routes/attachments.d.ts

@@ -0,0 +1,5 @@
+import { Hono } from 'hono';
+import type { AppEnv } from '../types.js';
+import type { StackContext } from '../stack.js';
+export declare function attachmentRoutes(ctx: StackContext, maxAttachmentBytes: number): Hono<AppEnv>;
+//# sourceMappingURL=attachments.d.ts.map

package/dist/routes/attachments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../../src/routes/attachments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAW5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CA8G5F"}

package/dist/routes/attachments.js

@@ -0,0 +1,104 @@
+import { Hono } from 'hono';
+import { bodyLimit } from 'hono/body-limit';
+import { StackPermissionError, StackPayloadTooLargeError } from '@haverstack/core';
+import { resolveAttachmentDownloadContentType, firstRecordedAttachment, parseUploadFilename, NOSNIFF_HEADER_NAME, NOSNIFF_HEADER_VALUE, } from '@haverstack/core/wire';
+import { serializeRecord } from '@haverstack/wire-types';
+import { requireAuth, requireOwner } from '../middleware/auth.js';
+export function attachmentRoutes(ctx, maxAttachmentBytes) {
+    const app = new Hono();
+    const { stack } = ctx;
+    const { ownerEntityId } = stack;
+    // Aborts while reading the body, the moment the byte count passes the
+    // limit — no full-body buffer for an oversized upload, chunked or not.
+    const attachmentBodyLimit = bodyLimit({
+        maxSize: maxAttachmentBytes,
+        onError: () => {
+            throw new StackPayloadTooLargeError(`Attachment exceeds the ${maxAttachmentBytes}-byte limit`);
+        },
+    });
+    // POST /attachments — stores the bytes and creates the _attachment@1
+    // metadata record in the same request, returning that record. Routed
+    // through ScopedStack.putAttachment() so the create-grant check on
+    // _attachment@1 runs before a single byte is written: an authenticated
+    // requester with no grant is refused, not merely denied a metadata
+    // record afterward. See docs/spec/wire-format.md § Upload.
+    app.post('/', attachmentBodyLimit, requireAuth(), async (c) => {
+        const auth = c.get('auth');
+        const mimeType = c.req.header('Content-Type') || 'application/octet-stream';
+        const filename = parseUploadFilename(c.req.header('Content-Disposition'));
+        const appId = c.req.query('appId') || undefined;
+        const data = new Uint8Array(await c.req.arrayBuffer());
+        const record = await stack.forSession(auth).putAttachment(data, mimeType, filename, appId);
+        return c.json(serializeRecord(record), 200);
+    });
+    // GET /attachments/:fileId — download
+    app.get('/:fileId', async (c) => {
+        const fileId = c.req.param('fileId');
+        const auth = c.get('auth');
+        let data;
+        try {
+            data = await (auth ? stack.forSession(auth) : stack.asEntity(null)).getAttachment(fileId);
+        }
+        catch (e) {
+            // Anonymous and denied is a transport-auth failure, distinct from an
+            // authenticated requester lacking access; everything else belongs to
+            // errorMiddleware. ScopedStack.getAttachment() already throws alike
+            // for missing and forbidden, so this handler owes no anti-oracle
+            // logic of its own — only to leave that answer intact.
+            if (!auth && e instanceof StackPermissionError) {
+                return c.json({ error: 'Unauthorized' }, 401);
+            }
+            throw e;
+        }
+        const metaRecords = await stack.getAttachmentRecords(fileId);
+        const firstRecord = firstRecordedAttachment(metaRecords);
+        const ownRecord = auth
+            ? firstRecordedAttachment(metaRecords.filter((r) => r.entityId === auth.subjectId))
+            : undefined;
+        const contentTypeParam = c.req.query('contentType');
+        const filenameParam = c.req.query('filename');
+        const { contentType, forced } = resolveAttachmentDownloadContentType({
+            contentTypeParam,
+            filenameParam,
+            storedMimeType: firstRecord?.content.mimeType,
+        });
+        // When the dangerous-type policy overrides the candidate, the filename
+        // goes too: forcing Content-Type alone won't stop a browser sniffing
+        // the body back into the original type without both nosniff and a
+        // non-inline disposition.
+        const filename = forced
+            ? undefined
+            : (filenameParam ?? ownRecord?.content.filename ?? firstRecord?.content.filename);
+        const disposition = filename
+            ? `attachment; filename*=UTF-8''${encodeURIComponent(filename)}`
+            : 'attachment';
+        return c.newResponse(data, 200, {
+            'Content-Type': contentType,
+            'Content-Length': String(data.byteLength),
+            'Content-Disposition': disposition,
+            [NOSNIFF_HEADER_NAME]: NOSNIFF_HEADER_VALUE,
+        });
+    });
+    // DELETE /attachments/:fileId
+    app.delete('/:fileId', requireOwner(ownerEntityId), async (c) => {
+        const fileId = c.req.param('fileId');
+        await stack.deleteAttachment(fileId);
+        return c.body(null, 204);
+    });
+    // POST /attachments/gc — sweep and delete orphaned attachment bytes.
+    // Owner-only, invoke-only (no built-in scheduling): dryRun makes a
+    // cron-from-outside workflow safe. Body is entirely optional — every
+    // field defaults inside ScopedStack.collectAttachmentGarbage().
+    app.post('/gc', requireOwner(ownerEntityId), async (c) => {
+        const auth = c.get('auth');
+        const raw = await c.req.text();
+        const body = raw ? JSON.parse(raw) : {};
+        const result = await stack.forSession(auth).collectAttachmentGarbage({
+            ...(typeof body.graceMs === 'number' && { graceMs: body.graceMs }),
+            ...(body.dryRun === true && { dryRun: true }),
+        });
+        return c.json(result, 200);
+    });
+    return app;
+}
+//# sourceMappingURL=attachments.js.map

package/dist/routes/attachments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.js","sourceRoot":"","sources":["../../src/routes/attachments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AACnF,OAAO,EACL,oCAAoC,EACpC,uBAAuB,EACvB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGzD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAElE,MAAM,UAAU,gBAAgB,CAAC,GAAiB,EAAE,kBAA0B;IAC5E,MAAM,GAAG,GAAG,IAAI,IAAI,EAAU,CAAC;IAC/B,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC;IACtB,MAAM,EAAE,aAAa,EAAE,GAAG,KAAK,CAAC;IAEhC,sEAAsE;IACtE,uEAAuE;IACvE,MAAM,mBAAmB,GAAG,SAAS,CAAC;QACpC,OAAO,EAAE,kBAAkB;QAC3B,OAAO,EAAE,GAAG,EAAE;YACZ,MAAM,IAAI,yBAAyB,CACjC,0BAA0B,kBAAkB,aAAa,CAC1D,CAAC;QACJ,CAAC;KACF,CAAC,CAAC;IAEH,qEAAqE;IACrE,qEAAqE;IACrE,mEAAmE;IACnE,uEAAuE;IACvE,mEAAmE;IACnE,2DAA2D;IAC3D,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,mBAAmB,EAAE,WAAW,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;QAC5D,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,0BAA0B,CAAC;QAC5E,MAAM,QAAQ,GAAG,mBAAmB,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC,CAAC;QAC1E,MAAM,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,SAAS,CAAC;QAEhD,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC;QACvD,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC3F,OAAO,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,sCAAsC;IACtC,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;QAC9B,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACrC,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAE3B,IAAI,IAAgB,CAAC;QACrB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QAC5F,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,qEAAqE;YACrE,qEAAqE;YACrE,oEAAoE;YACpE,iEAAiE;YACjE,uDAAuD;YACvD,IAAI,CAAC,IAAI,IAAI,CAAC,YAAY,oBAAoB,EAAE,CAAC;gBAC/C,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE,GAAG,CAAC,CAAC;YAChD,CAAC;YACD,MAAM,CAAC,CAAC;QACV,CAAC;QAED,MAAM,WAAW,GAAG,MAAM,KAAK,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC;QAC7D,MAAM,WAAW,GAAG,uBAAuB,CAAC,WAAW,CAAC,CAAC;QACzD,MAAM,SAAS,GAAG,IAAI;YACpB,CAAC,CAAC,uBAAuB,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC;YACnF,CAAC,CAAC,SAAS,CAAC;QAEd,MAAM,gBAAgB,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QACpD,MAAM,aAAa,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAE9C,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,oCAAoC,CAAC;YACnE,gBAAgB;YAChB,aAAa;YACb,cAAc,EAAE,WAAW,EAAE,OAAO,CAAC,QAAQ;SAC9C,CAAC,CAAC;QACH,uEAAuE;QACvE,qEAAqE;QACrE,kEAAkE;QAClE,0BAA0B;QAC1B,MAAM,QAAQ,GAAG,MAAM;YACrB,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,CAAC,aAAa,IAAI,SAAS,EAAE,OAAO,CAAC,QAAQ,IAAI,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;QAEpF,MAAM,WAAW,GAAG,QAAQ;YAC1B,CAAC,CAAC,gCAAgC,kBAAkB,CAAC,QAAQ,CAAC,EAAE;YAChE,CAAC,CAAC,YAAY,CAAC;QAEjB,OAAO,CAAC,CAAC,WAAW,CAAC,IAA0C,EAAE,GAAG,EAAE;YACpE,cAAc,EAAE,WAAW;YAC3B,gBAAgB,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC;YACzC,qBAAqB,EAAE,WAAW;YAClC,CAAC,mBAAmB,CAAC,EAAE,oBAAoB;SAC5C,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,8BAA8B;IAC9B,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,YAAY,CAAC,aAAa,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;QAC9D,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACrC,MAAM,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;QACrC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC3B,CAAC,CAAC,CAAC;IAEH,qEAAqE;IACrE,mEAAmE;IACnE,qEAAqE;IACrE,gEAAgE;IAChE,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,YAAY,CAAC,aAAa,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;QACvD,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAA4C,CAAC,CAAC,CAAC,EAAE,CAAC;QACpF,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,wBAAwB,CAAC;YACnE,GAAG,CAAC,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;YAClE,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;SAC9C,CAAC,CAAC;QACH,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;IAEH,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/routes/auth.d.ts

@@ -0,0 +1,6 @@
+import { Hono } from 'hono';
+import type { Logger } from 'pino';
+import type { AppEnv } from '../types.js';
+import type { StackContext } from '../stack.js';
+export declare function authRoutes(ctx: StackContext, authOrigin: string, logger: Logger): Hono<AppEnv>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/routes/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/routes/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAa5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA0BhD,wBAAgB,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CA+F9F"}

package/dist/routes/auth.js

@@ -0,0 +1,110 @@
+import { Hono } from 'hono';
+import { verifyAuthChallenge, base64urlDecode } from '@haverstack/core/wire';
+import { isValidDidKey } from '@haverstack/core/did';
+import { WIRE_AUTH_ERROR_STATUS } from '@haverstack/wire-types';
+import { readJson } from '../lib/json.js';
+import { createExpiredTokenSweeper } from '../lib/tokenSweep.js';
+// The handshake never issues a delegated token: proving key possession
+// proves the principal and nothing about whom it may act for. It gets a
+// default TTL rather than the owner's choice of one, because a token
+// anyone can mint for themselves owes a bounded lifetime.
+const AUTH_TOKEN_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+// Stamped on every handshake-issued token. GET /tokens is the owner's only
+// view of what exists, and without this a self-service token is
+// indistinguishable from one the owner minted deliberately — so "revoke
+// everything the handshake handed out" would be an unanswerable question.
+const AUTH_TOKEN_LABEL = 'did-challenge';
+/**
+ * `{ error: { code, message } }` for the four handshake-specific codes,
+ * deliberately outside WireErrorCode — no Stack operation has begun at
+ * this point, so none of these maps to a StackError. See
+ * docs/spec/wire-format.md § Authentication.
+ */
+function authError(c, code, message) {
+    return c.json({ error: { code, message } }, WIRE_AUTH_ERROR_STATUS[code]);
+}
+export function authRoutes(ctx, authOrigin, logger) {
+    const app = new Hono();
+    const sweepExpiredTokens = createExpiredTokenSweeper(ctx.tokens, logger);
+    // POST /auth/challenge — issues a nonce bound to the requested DID.
+    // Unauthenticated: this is how a token is earned in the first place.
+    app.post('/challenge', async (c) => {
+        const body = await readJson(c);
+        if (typeof body.did !== 'string' || !isValidDidKey(body.did)) {
+            return authError(c, 'invalid_did', 'Not a valid did:key');
+        }
+        const { nonce, expiresAt } = ctx.nonces.issue(body.did);
+        const response = { nonce, expiresAt: expiresAt.toISOString() };
+        return c.json(response);
+    });
+    // POST /auth/token — redeems a signed nonce for a bearer token.
+    // Unauthenticated for the same reason.
+    app.post('/token', async (c) => {
+        const body = await readJson(c);
+        if (typeof body.did !== 'string' || !isValidDidKey(body.did)) {
+            return authError(c, 'invalid_did', 'Not a valid did:key');
+        }
+        // Checked ahead of the signature so a nonce issued to a different DID
+        // is refused as unknown_nonce even when the caller's own signature over
+        // it is perfectly valid — the nonce belongs to the DID it was issued
+        // for, not to whoever can produce a valid signature.
+        if (typeof body.nonce !== 'string') {
+            return authError(c, 'unknown_nonce', 'Unknown or already-used nonce');
+        }
+        if (typeof body.signature !== 'string') {
+            return authError(c, 'invalid_signature', 'Signature does not verify');
+        }
+        // Spent on this call regardless of what happens next — single-use
+        // means a redemption attempt consumes the nonce, not merely a
+        // successful one.
+        const result = ctx.nonces.redeem(body.did, body.nonce);
+        if (result === 'unknown')
+            return authError(c, 'unknown_nonce', 'Unknown or already-used nonce');
+        if (result === 'expired')
+            return authError(c, 'expired_nonce', 'Challenge has expired');
+        let signatureBytes;
+        try {
+            signatureBytes = base64urlDecode(body.signature);
+        }
+        catch {
+            return authError(c, 'invalid_signature', 'Signature does not verify');
+        }
+        // Built from our own configured public origin (authOrigin), never from
+        // a request header — Host/X-Forwarded-Host are client-controlled, and
+        // deriving the signed origin from either would let a client choose
+        // which origin it signs for, silently reopening the relay attack the
+        // origin binding exists to prevent.
+        const verified = await verifyAuthChallenge({ origin: authOrigin, did: body.did, nonce: body.nonce }, signatureBytes).catch(() => false);
+        if (!verified)
+            return authError(c, 'invalid_signature', 'Signature does not verify');
+        // Reclaim expired rows before adding one. Throttled internally, so this
+        // is a no-op on all but the first handshake of each interval.
+        await sweepExpiredTokens();
+        // Undelegated by construction: principalId and subjectId are both the
+        // proven DID. Never let a client name its own subject.
+        const expiresAt = new Date(Date.now() + AUTH_TOKEN_TTL_MS);
+        const { token } = await ctx.tokens.createToken(body.did, {
+            expiresAt,
+            label: AUTH_TOKEN_LABEL,
+        });
+        // Reported from the value just written rather than read back through
+        // listTokens(), an unpaginated scan of every token ever issued — on an
+        // unauthenticated route that makes each handshake cost more than the
+        // last. The store persists the Date unchanged, so a read-back could
+        // only return what is already here.
+        const response = {
+            token,
+            expiresAt: expiresAt.toISOString(),
+            principalId: body.did,
+            subjectId: body.did,
+        };
+        // The one place a bearer token comes into existence without the owner
+        // doing anything, so it is the one place a log line is the only record
+        // that it happened. errorMiddleware already logs denied-but-verified
+        // requests; this is its counterpart on the granting side.
+        logger.info({ requestId: c.get('requestId'), did: body.did, expiresAt: expiresAt.toISOString() }, 'Issued a token via the DID challenge-response handshake');
+        return c.json(response);
+    });
+    return app;
+}
+//# sourceMappingURL=auth.js.map

package/dist/routes/auth.js.map

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

package/dist/routes/changes.d.ts

@@ -0,0 +1,22 @@
+import { Hono } from 'hono';
+import type { AppEnv } from '../types.js';
+import type { StackContext } from '../stack.js';
+import type { Config } from '../config.js';
+import type { Logger } from 'pino';
+export type ChangeRouteOptions = {
+    keepaliveMs?: number;
+    sessionCheckMs?: number;
+    maxPendingFrames?: number;
+    /**
+     * Whether a presented cursor is honored at all. Default true and never
+     * false in production, since discovery advertises resume unconditionally.
+     * It exists because `resume: false` is real, spec-defined behavior
+     * (`ready` with no `seq`, then `reset` with reason `not_supported`) that
+     * a conformance fixture needs a way to reach.
+     */
+    resume?: boolean;
+    resumeBufferDepth?: number;
+    resumeRetentionMs?: number;
+};
+export declare function changeRoutes(ctx: StackContext, config: Config, logger: Logger, opts?: ChangeRouteOptions): Hono<AppEnv>;
+//# sourceMappingURL=changes.d.ts.map

package/dist/routes/changes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changes.d.ts","sourceRoot":"","sources":["../../src/routes/changes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAG5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAM3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAuBnC,MAAM,MAAM,kBAAkB,GAAG;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAYF,wBAAgB,YAAY,CAC1B,GAAG,EAAE,YAAY,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,kBAAuB,GAC5B,IAAI,CAAC,MAAM,CAAC,CAqNd"}

package/dist/routes/changes.js

@@ -0,0 +1,233 @@
+import { Hono } from 'hono';
+import { streamSSE } from 'hono/streaming';
+import { StackQueryError, StackPermissionError } from '@haverstack/core';
+import { parseChangeParams } from '@haverstack/core/wire';
+import { serializeChange, isValidSeq } from '@haverstack/wire-types';
+import { safeCompare, isOwnerActingAlone } from '../middleware/auth.js';
+import { FrameGate } from '../lib/frameGate.js';
+import { decodeCursor } from '../lib/resumeCursor.js';
+import { ResumeBufferRegistry, resumeBufferKey } from '../lib/resumeBuffer.js';
+// Keepalive cadence, and how often an authenticated session is re-checked
+// against the token store — a stream's authority is fixed at connect, so
+// without the re-check a revoked token keeps delivering for as long as the
+// connection lives. Neither value reaches a client, so neither is an env var.
+const DEFAULT_KEEPALIVE_MS = 15_000;
+const DEFAULT_SESSION_CHECK_MS = 30_000;
+// A client whose in-flight frame count crosses this is closed rather than
+// left to queue: one that can't tell it missed a frame can't repair it
+// either, so dropping silently is worse than disconnecting.
+const DEFAULT_MAX_PENDING_FRAMES = 1000;
+// Per-buffer ring depth and how long a buffer keeps being fed after its
+// last connection disconnects — see src/lib/resumeBuffer.ts. Not part of
+// the wire contract either: a client never learns these numbers, only
+// their consequence (`overflow` or `cursor_expired`).
+const DEFAULT_RESUME_BUFFER_DEPTH = 1000;
+const DEFAULT_RESUME_RETENTION_MS = 5 * 60 * 1000;
+/**
+ * Raw cursor text presented on this connection, if any — `Last-Event-ID`
+ * takes priority over `?since=` (a browser EventSource-style reconnect
+ * sends the header; `?since=` exists for a client whose transport can't
+ * set one). Not yet validated or decoded — see isValidSeq()/decodeCursor().
+ */
+function presentedCursorRaw(c, url) {
+    return c.req.header('Last-Event-ID') ?? url.searchParams.get('since') ?? undefined;
+}
+export function changeRoutes(ctx, config, logger, opts = {}) {
+    const app = new Hono();
+    const keepaliveMs = opts.keepaliveMs ?? DEFAULT_KEEPALIVE_MS;
+    const sessionCheckMs = opts.sessionCheckMs ?? DEFAULT_SESSION_CHECK_MS;
+    const maxPendingFrames = opts.maxPendingFrames ?? DEFAULT_MAX_PENDING_FRAMES;
+    const resumeEnabled = opts.resume ?? true;
+    const resumeBuffers = new ResumeBufferRegistry({
+        depth: opts.resumeBufferDepth ?? DEFAULT_RESUME_BUFFER_DEPTH,
+        retentionMs: opts.resumeRetentionMs ?? DEFAULT_RESUME_RETENTION_MS,
+    });
+    /** Scope to a session if authenticated, else the anonymous (public-only) view. */
+    function scopeFor(auth) {
+        return auth ? ctx.stack.forSession(auth) : ctx.stack.asEntity(null);
+    }
+    // Single-process only: events exist only in the process owning the
+    // stack's storage (docs/spec/wire-format.md § Feed implementation
+    // checklist), and query workers only read. A second process subscribing
+    // to its own Stack over the same storage would see nothing and look fine
+    // in testing — worth knowing before scaling this horizontally.
+    app.get('/', async (c) => {
+        const url = new URL(c.req.url);
+        const auth = c.get('auth');
+        const { filter, includeRecords, includeUnlisted } = parseChangeParams(url);
+        const presentedRaw = presentedCursorRaw(c, url);
+        // Refused before the stream opens: a throw from subscribe() after
+        // streaming starts is caught below and merely closes the connection,
+        // silently, having already answered 200. includeUnlisted owes a real
+        // 403, the same one GET /records answers with.
+        if (includeUnlisted && !isOwnerActingAlone(auth, ctx.stack.ownerEntityId)) {
+            throw new StackPermissionError('includeUnlisted is owner-only');
+        }
+        // A charset-invalid cursor is refused rather than treated as a cache
+        // miss: no conformant server could have minted it, so there is nothing
+        // to reconcile. isValidSeq() is the rule minted cursors meet on the way
+        // out, applied here on the way in.
+        if (resumeEnabled && presentedRaw !== undefined && !isValidSeq(presentedRaw)) {
+            throw new StackQueryError(`Invalid cursor: "${presentedRaw}"`);
+        }
+        // Never accepted: a bearer token is read only from the Authorization
+        // header (authMiddleware), never from a query param — the feed is
+        // consumed via fetch with a streaming body precisely so a client never
+        // needs to put a credential somewhere a browser might log or cache it.
+        const bearerToken = c.req.header('Authorization')?.slice('Bearer '.length);
+        return streamSSE(c, async (stream) => {
+            let resolveDone;
+            const done = new Promise((resolve) => {
+                resolveDone = resolve;
+            });
+            stream.onAbort(() => resolveDone());
+            const unregister = ctx.changeStreams.add(() => resolveDone());
+            const gate = new FrameGate(maxPendingFrames, () => resolveDone());
+            /** Returns false once the gate has tripped — this connection is closing. */
+            function send(event, data, id) {
+                return gate.send(() => stream.writeSSE({ event, data: JSON.stringify(data), ...(id !== undefined && { id }) }));
+            }
+            // Assigned inside the try below; torn down in the finally whether the
+            // connection ended by abort, by a revoked session, or by a throw. A
+            // throw is caught rather than left to hono, which would answer it by
+            // writing the raw error message to the client as an `error` frame.
+            let unsubscribe;
+            let keepalive;
+            let sessionCheck;
+            try {
+                if (!resumeEnabled) {
+                    // `resume: false` — a discovery-conformant server that mints no
+                    // cursors at all, reachable only through WellknownRouteOptions'
+                    // matching test toggle.
+                    send('ready', {});
+                    if (presentedRaw !== undefined) {
+                        const reason = 'not_supported';
+                        send('reset', { reason });
+                    }
+                    unsubscribe = await scopeFor(auth).subscribe((change) => {
+                        send('record', serializeChange(change));
+                    }, { filter, includeRecords, includeUnlisted });
+                }
+                else {
+                    const key = resumeBufferKey({
+                        principalId: auth?.principalId ?? null,
+                        subjectId: auth?.subjectId ?? null,
+                        filter,
+                        includeRecords,
+                        includeUnlisted,
+                    });
+                    const scoped = scopeFor(auth);
+                    const buffer = await resumeBuffers.acquire(key, (onChange) => scoped.subscribe(onChange, { filter, includeRecords, includeUnlisted }));
+                    // Attached before anything below awaits, so there is no gap
+                    // between what the backlog snapshot covers and what the live
+                    // buffer reports. `replaying` holds live arrivals until the
+                    // permission-rechecking replay finishes, so a change appended
+                    // mid-replay can't overtake an older, still-pending backlog frame.
+                    let replaying = true;
+                    const queued = [];
+                    const detachLive = buffer.subscribeLive((entry) => {
+                        if (replaying)
+                            queued.push(entry);
+                        else
+                            send('record', entry.frame, entry.frame.seq);
+                    });
+                    // Registered before the first `await` below, so a subscription
+                    // opened above is always released — including when that await
+                    // throws. Everything after this point runs under the finally.
+                    unsubscribe = () => {
+                        detachLive();
+                        resumeBuffers.release(key);
+                    };
+                    let resetReason;
+                    let backlog = [];
+                    if (presentedRaw !== undefined) {
+                        const decoded = decodeCursor(presentedRaw);
+                        if (!decoded || decoded.bufferId !== buffer.id) {
+                            // Unrecognized outright, or names a buffer instance that isn't
+                            // this key's current one (evicted past its retention window,
+                            // or minted for a filter this cursor doesn't actually match).
+                            resetReason = 'cursor_expired';
+                        }
+                        else {
+                            const outcome = buffer.entriesAfter(decoded.n);
+                            if (outcome.status === 'ok')
+                                backlog = outcome.entries;
+                            else
+                                resetReason = outcome.status;
+                        }
+                    }
+                    send('ready', { seq: buffer.headCursor() });
+                    if (resetReason) {
+                        send('reset', { reason: resetReason });
+                    }
+                    else {
+                        for (const entry of backlog) {
+                            // A purge frame isn't re-checkable: the mutation-time
+                            // decision is the only one there will ever be
+                            // (docs/spec/events.md). Everything else still has its record
+                            // ID, so a grant revoked during the gap is caught here.
+                            if (!entry.isPurge) {
+                                const stillReadable = await scoped.get(entry.recordId);
+                                if (!stillReadable)
+                                    continue;
+                            }
+                            // Once the gate trips this connection is closing, so the
+                            // remaining entries are permission checks nobody will read.
+                            if (!send('record', entry.frame, entry.frame.seq))
+                                break;
+                        }
+                    }
+                    replaying = false;
+                    for (const entry of queued) {
+                        if (!send('record', entry.frame, entry.frame.seq))
+                            break;
+                    }
+                }
+                // Through the gate like any other write: a client not draining its
+                // keepalives isn't draining anything, and counting them is what
+                // keeps "in-flight frames are bounded" true of the whole stream
+                // rather than of `record` frames alone.
+                keepalive = setInterval(() => {
+                    gate.send(() => stream.write(': keepalive\n\n'));
+                }, keepaliveMs);
+                // A revoked or expired token must stop delivering. The owner's
+                // static bearer token never expires (authMiddleware compares it
+                // directly, not via the token store), so only a minted session needs
+                // re-checking; an anonymous connection has no token to revoke.
+                const isOwnerToken = bearerToken !== undefined && safeCompare(bearerToken, config.ownerToken);
+                sessionCheck =
+                    auth && !isOwnerToken && bearerToken
+                        ? setInterval(() => {
+                            void ctx.tokens.lookupToken(bearerToken).then((session) => {
+                                if (!session)
+                                    resolveDone();
+                            }, 
+                            // The token store is unreachable. Closing is the honest
+                            // answer — the client reconnects and re-authenticates
+                            // through the path that already handles a 401 — and it
+                            // keeps a rejection here from going unhandled.
+                            () => resolveDone());
+                        }, sessionCheckMs)
+                        : undefined;
+                await done;
+            }
+            catch (err) {
+                // Hono answers an uncaught throw here by writing the raw error
+                // message to the client as an `error` frame. Catching keeps internal
+                // detail off a stream any anonymous caller can open, and a closed
+                // connection is a repair the client already knows how to make.
+                logger.error({ err, requestId: c.get('requestId') }, 'Change feed connection ended with an error');
+            }
+            finally {
+                if (keepalive)
+                    clearInterval(keepalive);
+                if (sessionCheck)
+                    clearInterval(sessionCheck);
+                unsubscribe?.();
+                unregister();
+            }
+        });
+    });
+    return app;
+}
+//# sourceMappingURL=changes.js.map

package/dist/routes/changes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changes.js","sourceRoot":"","sources":["../../src/routes/changes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAK3C,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGrE,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAoB,MAAM,wBAAwB,CAAC;AAEjG,0EAA0E;AAC1E,yEAAyE;AACzE,2EAA2E;AAC3E,8EAA8E;AAC9E,MAAM,oBAAoB,GAAG,MAAM,CAAC;AACpC,MAAM,wBAAwB,GAAG,MAAM,CAAC;AACxC,0EAA0E;AAC1E,uEAAuE;AACvE,4DAA4D;AAC5D,MAAM,0BAA0B,GAAG,IAAI,CAAC;AACxC,wEAAwE;AACxE,yEAAyE;AACzE,sEAAsE;AACtE,sDAAsD;AACtD,MAAM,2BAA2B,GAAG,IAAI,CAAC;AACzC,MAAM,2BAA2B,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAkBlD;;;;;GAKG;AACH,SAAS,kBAAkB,CAAC,CAAkB,EAAE,GAAQ;IACtD,OAAO,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,IAAI,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,SAAS,CAAC;AACrF,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,GAAiB,EACjB,MAAc,EACd,MAAc,EACd,OAA2B,EAAE;IAE7B,MAAM,GAAG,GAAG,IAAI,IAAI,EAAU,CAAC;IAC/B,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,oBAAoB,CAAC;IAC7D,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,wBAAwB,CAAC;IACvE,MAAM,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,IAAI,0BAA0B,CAAC;IAC7E,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC;IAC1C,MAAM,aAAa,GAAG,IAAI,oBAAoB,CAAC;QAC7C,KAAK,EAAE,IAAI,CAAC,iBAAiB,IAAI,2BAA2B;QAC5D,WAAW,EAAE,IAAI,CAAC,iBAAiB,IAAI,2BAA2B;KACnE,CAAC,CAAC;IAEH,kFAAkF;IAClF,SAAS,QAAQ,CAAC,IAAyB;QACzC,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACtE,CAAC;IAED,mEAAmE;IACnE,kEAAkE;IAClE,wEAAwE;IACxE,yEAAyE;IACzE,+DAA+D;IAC/D,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;QACvB,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC/B,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC3B,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,eAAe,EAAE,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;QAC3E,MAAM,YAAY,GAAG,kBAAkB,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAEhD,kEAAkE;QAClE,qEAAqE;QACrE,qEAAqE;QACrE,+CAA+C;QAC/C,IAAI,eAAe,IAAI,CAAC,kBAAkB,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC;YAC1E,MAAM,IAAI,oBAAoB,CAAC,+BAA+B,CAAC,CAAC;QAClE,CAAC;QAED,qEAAqE;QACrE,uEAAuE;QACvE,wEAAwE;QACxE,mCAAmC;QACnC,IAAI,aAAa,IAAI,YAAY,KAAK,SAAS,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YAC7E,MAAM,IAAI,eAAe,CAAC,oBAAoB,YAAY,GAAG,CAAC,CAAC;QACjE,CAAC;QAED,qEAAqE;QACrE,kEAAkE;QAClE,uEAAuE;QACvE,uEAAuE;QACvE,MAAM,WAAW,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAE3E,OAAO,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;YACnC,IAAI,WAAwB,CAAC;YAC7B,MAAM,IAAI,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;gBACzC,WAAW,GAAG,OAAO,CAAC;YACxB,CAAC,CAAC,CAAC;YACH,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;YACpC,MAAM,UAAU,GAAG,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;YAE9D,MAAM,IAAI,GAAG,IAAI,SAAS,CAAC,gBAAgB,EAAE,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;YAClE,4EAA4E;YAC5E,SAAS,IAAI,CAAC,KAAa,EAAE,IAAa,EAAE,EAAW;gBACrD,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CACpB,MAAM,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,SAAS,IAAI,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CACxF,CAAC;YACJ,CAAC;YAED,sEAAsE;YACtE,oEAAoE;YACpE,qEAAqE;YACrE,mEAAmE;YACnE,IAAI,WAAqC,CAAC;YAC1C,IAAI,SAAqC,CAAC;YAC1C,IAAI,YAAwC,CAAC;YAE7C,IAAI,CAAC;gBACH,IAAI,CAAC,aAAa,EAAE,CAAC;oBACnB,gEAAgE;oBAChE,gEAAgE;oBAChE,wBAAwB;oBACxB,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;oBAClB,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;wBAC/B,MAAM,MAAM,GAAsB,eAAe,CAAC;wBAClD,IAAI,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;oBAC5B,CAAC;oBACD,WAAW,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,SAAS,CAC1C,CAAC,MAAoB,EAAE,EAAE;wBACvB,IAAI,CAAC,QAAQ,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC;oBAC1C,CAAC,EACD,EAAE,MAAM,EAAE,cAAc,EAAE,eAAe,EAAE,CAC5C,CAAC;gBACJ,CAAC;qBAAM,CAAC;oBACN,MAAM,GAAG,GAAG,eAAe,CAAC;wBAC1B,WAAW,EAAE,IAAI,EAAE,WAAW,IAAI,IAAI;wBACtC,SAAS,EAAE,IAAI,EAAE,SAAS,IAAI,IAAI;wBAClC,MAAM;wBACN,cAAc;wBACd,eAAe;qBAChB,CAAC,CAAC;oBACH,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;oBAC9B,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,EAAE,CAC3D,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC,CACxE,CAAC;oBAEF,4DAA4D;oBAC5D,6DAA6D;oBAC7D,4DAA4D;oBAC5D,8DAA8D;oBAC9D,mEAAmE;oBACnE,IAAI,SAAS,GAAG,IAAI,CAAC;oBACrB,MAAM,MAAM,GAAkB,EAAE,CAAC;oBACjC,MAAM,UAAU,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC,KAAK,EAAE,EAAE;wBAChD,IAAI,SAAS;4BAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;;4BAC7B,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;oBACpD,CAAC,CAAC,CAAC;oBACH,+DAA+D;oBAC/D,8DAA8D;oBAC9D,8DAA8D;oBAC9D,WAAW,GAAG,GAAG,EAAE;wBACjB,UAAU,EAAE,CAAC;wBACb,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;oBAC7B,CAAC,CAAC;oBAEF,IAAI,WAA0C,CAAC;oBAC/C,IAAI,OAAO,GAAkB,EAAE,CAAC;oBAChC,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;wBAC/B,MAAM,OAAO,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;wBAC3C,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,QAAQ,KAAK,MAAM,CAAC,EAAE,EAAE,CAAC;4BAC/C,+DAA+D;4BAC/D,6DAA6D;4BAC7D,8DAA8D;4BAC9D,WAAW,GAAG,gBAAgB,CAAC;wBACjC,CAAC;6BAAM,CAAC;4BACN,MAAM,OAAO,GAAG,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;4BAC/C,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI;gCAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;;gCAClD,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;wBACpC,CAAC;oBACH,CAAC;oBAED,IAAI,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;oBAE5C,IAAI,WAAW,EAAE,CAAC;wBAChB,IAAI,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;oBACzC,CAAC;yBAAM,CAAC;wBACN,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;4BAC5B,sDAAsD;4BACtD,8CAA8C;4BAC9C,8DAA8D;4BAC9D,wDAAwD;4BACxD,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;gCACnB,MAAM,aAAa,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gCACvD,IAAI,CAAC,aAAa;oCAAE,SAAS;4BAC/B,CAAC;4BACD,yDAAyD;4BACzD,4DAA4D;4BAC5D,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC;gCAAE,MAAM;wBAC3D,CAAC;oBACH,CAAC;oBAED,SAAS,GAAG,KAAK,CAAC;oBAClB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;wBAC3B,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC;4BAAE,MAAM;oBAC3D,CAAC;gBACH,CAAC;gBAED,mEAAmE;gBACnE,gEAAgE;gBAChE,gEAAgE;gBAChE,wCAAwC;gBACxC,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;oBAC3B,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,CAAC;gBACnD,CAAC,EAAE,WAAW,CAAC,CAAC;gBAEhB,+DAA+D;gBAC/D,gEAAgE;gBAChE,qEAAqE;gBACrE,+DAA+D;gBAC/D,MAAM,YAAY,GAChB,WAAW,KAAK,SAAS,IAAI,WAAW,CAAC,WAAW,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;gBAC3E,YAAY;oBACV,IAAI,IAAI,CAAC,YAAY,IAAI,WAAW;wBAClC,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE;4BACf,KAAK,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,IAAI,CAC3C,CAAC,OAAO,EAAE,EAAE;gCACV,IAAI,CAAC,OAAO;oCAAE,WAAW,EAAE,CAAC;4BAC9B,CAAC;4BACD,wDAAwD;4BACxD,sDAAsD;4BACtD,uDAAuD;4BACvD,+CAA+C;4BAC/C,GAAG,EAAE,CAAC,WAAW,EAAE,CACpB,CAAC;wBACJ,CAAC,EAAE,cAAc,CAAC;wBACpB,CAAC,CAAC,SAAS,CAAC;gBAEhB,MAAM,IAAI,CAAC;YACb,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,+DAA+D;gBAC/D,qEAAqE;gBACrE,kEAAkE;gBAClE,+DAA+D;gBAC/D,MAAM,CAAC,KAAK,CACV,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,EACtC,4CAA4C,CAC7C,CAAC;YACJ,CAAC;oBAAS,CAAC;gBACT,IAAI,SAAS;oBAAE,aAAa,CAAC,SAAS,CAAC,CAAC;gBACxC,IAAI,YAAY;oBAAE,aAAa,CAAC,YAAY,CAAC,CAAC;gBAC9C,WAAW,EAAE,EAAE,CAAC;gBAChB,UAAU,EAAE,CAAC;YACf,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/routes/entity.d.ts

@@ -0,0 +1,5 @@
+import { Hono } from 'hono';
+import type { AppEnv } from '../types.js';
+import type { StackContext } from '../stack.js';
+export declare function entityRoutes(ctx: StackContext): Hono<AppEnv>;
+//# sourceMappingURL=entity.d.ts.map

package/dist/routes/entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../src/routes/entity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAMhD,wBAAgB,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,CAwB5D"}