@kedge/server 0.9.0 → 0.10.0

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@kedge/server",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/chandeldivyam/Kedge.git",
     "directory": "packages/server"
   },
+  "engines": {
+    "node": ">=24"
+  },
   "type": "module",
   "description": "Hono app: /store, /admin, /health.",
   "exports": {
@@ -19,8 +22,8 @@
     "hono": "4.13.13",
     "@hono/zod-openapi": "1.6.3",
     "zod": "4.6.7",
-    "@kedge/core": "0.9.0",
-    "@kedge/plugin-sdk": "0.9.0"
+    "@kedge/core": "0.10.0",
+    "@kedge/plugin-sdk": "0.10.0"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "5.20261024.1"

package/src/access.ts

@@ -307,6 +307,11 @@ export function adminGate(auth: AuthDeps, perms: AdminPermissions, now: () => nu
     if (cred?.via === "bearer" && cred.token.startsWith("sk_")) {
       const found = await resolveKey(c, auth, cred.token, t);
       access = { ctx: found.ctx, via: "key", key: found.key, resolved: found };
+    } else if (cred?.via === "bearer" && cred.token.startsWith("kcs_")) {
+      // A CLI session (p0.10 §6.2): admitted here, on /admin/* only, never as a staff session.
+      const found = await auth.access.cliSession(cred.token, t);
+      if (!found) throw new KedgeError("UNAUTHORIZED", "This CLI session has ended; run the command again");
+      access = { ctx: found.ctx, via: "bearer", resolved: found };
     } else if (cred) {
       access = await resolveSession(c, auth, "staff", cred, t);
     } else {

package/src/admin-routes.ts

@@ -485,14 +485,18 @@ export function adminRoutes(
       createRoute({
         method: "put",
         path: "/admin/storefronts/{id}/origins",
-        request: { params: z.object({ id: ID }), ...jsonBody(z.object({ allowed_origins: Origins })) },
+        request: {
+          params: z.object({ id: ID }),
+          // `expected`: the list as the caller read it; the write is refused CONFLICT if it changed since.
+          ...jsonBody(z.object({ allowed_origins: Origins, expected: Origins.optional() })),
+        },
         responses: ok("The storefront's origins"),
       }),
     ),
     async (c) => {
       const { id } = c.req.valid("param");
-      const { allowed_origins } = c.req.valid("json");
-      await admin.setOrigins(ctx(c), id, allowed_origins, req(c));
+      const { allowed_origins, expected } = c.req.valid("json");
+      await admin.setOrigins(ctx(c), id, allowed_origins, req(c), expected);
       return c.json({ id, allowed_origins }, 200);
     },
   );
@@ -575,6 +579,78 @@ export function adminRoutes(
     },
   );
 
+  // ---- credential references (p0.10 §6.2) ----------------------------------------------
+  // The permission depends on the ref's kind (api_key:write for a secret key,
+  // storefront:write otherwise), so the store authorizes inside its own batch.
+
+  const Ref = z.object({ ref: z.string().regex(/^[A-Za-z0-9_-]{32,128}$/) });
+  const RefKind = z.enum(["secret", "publishable", "storefront"]);
+  const refJson = (r: {
+    ref: string;
+    kind: string;
+    state: string;
+    storefrontId: string | null;
+    keyId: string | null;
+  }) => ({ ref: r.ref, kind: r.kind, state: r.state, storefront_id: r.storefrontId, key_id: r.keyId });
+  app.openapi(
+    perms.declare(
+      { permission: "api_key:write", store: true },
+      createRoute({
+        method: "put",
+        path: "/admin/credential-refs/{ref}",
+        request: {
+          params: Ref,
+          ...jsonBody(
+            z.discriminatedUnion("kind", [
+              z.object({
+                kind: z.literal("secret"),
+                name: z.string().min(1).max(80),
+                grants: Grants.min(1),
+                location_ids: z.array(ID).max(64).optional(),
+              }),
+              z.object({ kind: z.literal("publishable"), name: z.string().min(1).max(80), storefront_id: ID }),
+              z.object({ kind: z.literal("storefront"), name: z.string().min(1).max(80), allowed_origins: Origins }),
+            ]),
+          ),
+        },
+        responses: ok("The key the ref made, shown once; CREDENTIAL_REF_TAKEN if it was used or voided"),
+      }),
+    ),
+    async (c) => {
+      once(c);
+      const b = c.req.valid("json");
+      const made = await admin.createByRef(
+        ctx(c),
+        c.req.valid("param").ref,
+        b.kind === "secret"
+          ? {
+              kind: "secret",
+              name: b.name,
+              grants: grants(b.grants),
+              ...(b.location_ids ? { locationIds: b.location_ids } : {}),
+            }
+          : b.kind === "publishable"
+            ? { kind: "publishable", name: b.name, storefrontId: b.storefront_id }
+            : { kind: "storefront", name: b.name, allowedOrigins: b.allowed_origins },
+        req(c),
+      );
+      return c.json({ ...refJson(made), key: made.key, token_prefix: made.tokenPrefix }, 200);
+    },
+  );
+  app.openapi(
+    perms.declare(
+      { permission: "api_key:write", store: true },
+      createRoute({
+        method: "post",
+        path: "/admin/credential-refs/{ref}/void",
+        request: { params: Ref, ...jsonBody(z.object({ kind: RefKind })) },
+        responses: ok("The ref's outcome, kept for ever: fenced, or revoked with what it made"),
+      }),
+    ),
+    async (c) =>
+      c.json(refJson(await admin.voidRef(ctx(c), c.req.valid("param").ref, c.req.valid("json").kind, req(c))), 200),
+  );
+
   // ---- API keys ----------------------------------------------------------------------
 
   const KeyParam = z.object({ id: ID });

package/src/entity-routes.ts

@@ -184,22 +184,26 @@ export function entityRoutes(
           method: "post",
           path: `${base}/search`,
           request: jsonBody(
-            z.object({
-              filters: z
-                .array(z.object({ field: z.string(), op: z.enum(["eq", "in", "gte", "lt"]), value: z.unknown() }))
-                .max(16)
-                .optional(),
-              search: z
-                .object({
-                  fields: z.array(z.string()).min(1).max(ENTITY_LIMITS.SEARCH_FIELDS_MAX),
-                  term: z.string().min(1).max(200),
-                })
-                .optional(),
-              sort: z.string().max(64).optional(),
-              state: z.enum(["live", "archived"]).optional(),
-              cursor: z.string().max(2048).optional(),
-              limit: z.number().int().min(1).max(100).optional(),
-            }),
+            z
+              .object({
+                filters: z
+                  .array(z.object({ field: z.string(), op: z.enum(["eq", "in", "gte", "lt"]), value: z.unknown() }))
+                  .max(16)
+                  .optional(),
+                search: z
+                  .object({
+                    fields: z.array(z.string()).min(1).max(ENTITY_LIMITS.SEARCH_FIELDS_MAX),
+                    term: z.string().min(1).max(200),
+                  })
+                  .optional(),
+                sort: z.string().max(64).optional(),
+                state: z.enum(["live", "archived"]).optional(),
+                cursor: z.string().max(2048).optional(),
+                limit: z.number().int().min(1).max(100).optional(),
+              })
+              // A key it doesn't know is refused, naming it, never ignored: a mistyped `filter`
+              // would otherwise answer every row as if it had narrowed them (D-068).
+              .strict(),
           ),
           responses: ok(`A page of ${def.label}, classified values in the body`),
         }),

package/src/types.ts

@@ -231,6 +231,8 @@ export interface AccessStore {
   /** Staff activity or a customer renewal; the renewed expiry, if any. */
   maintain(session: AccessSession, now: number): Promise<number | null>;
   apiKey(presented: string, now: number): Promise<ResolvedAccess | null>;
+  /** A CLI session's principal (p0.10 §6.2), or null when the token names no unexpired one. */
+  cliSession(token: string, now: number): Promise<ResolvedAccess | null>;
   keyTouchDue(key: { lastUsedAt: number | null }, now: number): boolean;
   touchKey(keyId: string, now: number): Promise<void>;
   /** Counts a failed key verification against the address; false once past the limit (§4.3). */
@@ -365,6 +367,20 @@ export interface IssuedInvite {
   token: string;
   expiresAt: number;
 }
+/** What a credential reference made, kept for ever (p0.10 §6.2). */
+export interface CredentialRefState {
+  ref: string;
+  kind: "secret" | "publishable" | "storefront";
+  state: "used" | "fenced" | "revoked";
+  storefrontId: string | null;
+  keyId: string | null;
+}
+
+export type CredentialRefCreate =
+  | { kind: "secret"; name: string; grants: readonly GrantInput[]; locationIds?: readonly string[] }
+  | { kind: "publishable"; name: string; storefrontId: string }
+  | { kind: "storefront"; name: string; allowedOrigins: readonly string[] };
+
 export interface IssuedKey {
   id: string;
   key: string;
@@ -443,6 +459,8 @@ export interface AdminStore {
     storefrontId: string,
     allowedOrigins: readonly string[],
     req?: AdminRequest,
+    /** The list the caller read: the write is refused CONFLICT if it changed since. */
+    expected?: readonly string[],
   ): Promise<void>;
   createSecretKey(
     ctx: AccessContext,
@@ -461,6 +479,20 @@ export interface AdminStore {
     req?: AdminRequest,
     storefrontId?: string,
   ): Promise<{ id: string; revokedAt: number | null }>;
+  /** A key made under a caller-chosen ref: at most one, ever (p0.10 §6.2). */
+  createByRef(
+    ctx: AccessContext,
+    ref: string,
+    input: CredentialRefCreate,
+    req?: AdminRequest,
+  ): Promise<CredentialRefState & IssuedKey>;
+  /** Settles a ref for good: fenced when unused, its key revoked when used. */
+  voidRef(
+    ctx: AccessContext,
+    ref: string,
+    kind: CredentialRefState["kind"],
+    req?: AdminRequest,
+  ): Promise<CredentialRefState>;
   rotateKey(
     ctx: AccessContext,
     keyId: string,