@gate-forge/pack-auth 0.1.0

package/dist/index.js

@@ -0,0 +1,40 @@
+/**
+ * @gate-forge/pack-auth — Authorization discovery pack.
+ *
+ * Detects role-guard + tenant-isolation patterns in TypeScript / JavaScript
+ * HTTP route definitions and emits one `auth.resource` per guarded
+ * endpoint. Each resource carries `attributes.roleRequirement` (string[]
+ * of accepted roles) and `attributes.tenancy` (`'tenant-bound' | 'none'`),
+ * which the policy engine maps onto the auth obligation vocabulary.
+ *
+ * Vocabulary:
+ *
+ *   - `auth:role-allowed` — the principal with the required role reaches
+ *     the handler and produces the handler's success status.
+ *   - `auth:role-denied` — the authenticated principal WITHOUT the
+ *     required role is rejected with 401/403 BEFORE state mutation.
+ *   - `auth:tenant-isolated` — a principal of a different tenant than
+ *     the target entity is rejected (cross-tenant guard).
+ *   - `auth:denied-no-side-effect` — a denied request leaves the
+ *     persisted entity UNCHANGED (verified by a follow-up GET).
+ *   - `auth:forged-token-rejected` — a token whose signature does not
+ *     validate is rejected with 401 and never reaches the handler.
+ *
+ * Limitations (documented in the README):
+ *
+ *   - Python/FastAPI `Depends()` patterns are NOT covered by this pack —
+ *     the brief restricts the detector to TS/JS. The FastAPI equivalent
+ *     is deferred to a future pack.
+ *   - The detector does NOT cross-reference role identity providers; a
+ *     `requireRole('admin')` call site is treated as authoritative for
+ *     classification. Production users MUST classify role lists in the
+ *     project config to bind them to a known taxonomy.
+ */
+import { createAuthDetector } from './detector.js';
+export { PACK_PLUGIN_ID, PACK_VERSION } from './version.js';
+export { createAuthDetector, } from './detector.js';
+export { AuthEntityAdapterSchema, validateAuthEntityAdapter, } from './adapter-schema.js';
+export { AUTH_OBLIGATION_CONTRACTS, obligationId, } from './obligations.js';
+/** The default CLI in-process plugin module: `{ discover(paths) }`. */
+export default createAuthDetector();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EACL,kBAAkB,GAKnB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,uBAAuB,EACvB,yBAAyB,GAK1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,yBAAyB,EACzB,YAAY,GAEb,MAAM,kBAAkB,CAAC;AAE1B,uEAAuE;AACvE,eAAe,kBAAkB,EAAE,CAAC"}

package/dist/obligations.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The auth pack obligation vocabulary.
+ *
+ * Every obligation id is `<resourceId>:<contract>` where `<resourceId>` is
+ * the stable id the detector emits for one guarded endpoint
+ * (`auth.<method>.<path>`) and `<contract>` is one of the names below.
+ *
+ * Contract grammar: `auth:<verb>` where interior colons are NOT legal
+ * (these contracts do not carry their own namespace segment). Trailing
+ * colons are rejected by `ContractNameSchema` upstream.
+ *
+ * Vocabulary rationale (per the pack brief):
+ *
+ * - `auth:role-allowed` — A request with an authenticated principal whose
+ *   role satisfies the endpoint's `roleRequirement` reaches the handler.
+ *   Verified by issuing the request with a valid token carrying the
+ *   required role; the handler MUST produce its declared success status
+ *   (200 / 303 / 201).
+ *
+ * - `auth:role-denied` — A request whose principal is authenticated but
+ *   LACKS the required role is rejected with 401/403 BEFORE any state
+ *   mutation. Verified by issuing the same request with a role that does
+ *   not satisfy `roleRequirement`; the response MUST be a denial status
+ *   and MUST NOT mutate persisted state (this obligation AND
+ *   `auth:denied-no-side-effect` together prove "deny is deny").
+ *
+ * - `auth:tenant-isolated` — A request whose tenant claim differs from
+ *   the tenant bound to the target entity is rejected (the endpoint's
+ *   `attributes.tenancy` is `tenant-bound`; the example server enforces
+ *   `req.user.tenantId === target.tenantId`). Verified by replaying the
+ *   admin request with the token of a different tenant; response is
+ *   denial status, no read or write succeeds.
+ *
+ * - `auth:denied-no-side-effect` — A denied request produces no persisted
+ *   side effect. Verified by: (a) asserting the denial status, then
+ *   (b) issuing a GET on the resource — the entity is unchanged from the
+ *   pre-denied snapshot. This is the "deny is deny, not pretend" check
+ *   that catches "200 OK with empty body" fake-greens.
+ *
+ * - `auth:forged-token-rejected` — A request carrying a token whose
+ *   signature does not validate (or whose payload fails verification)
+ *   is rejected with 401 and never reaches the handler. Verified by
+ *   mutating one byte of a valid token and asserting 401; the witness
+ *   GET shows the entity is untouched.
+ */
+export declare const AUTH_OBLIGATION_CONTRACTS: readonly ["auth:role-allowed", "auth:role-denied", "auth:tenant-isolated", "auth:denied-no-side-effect", "auth:forged-token-rejected"];
+/** One auth obligation contract name. */
+export type AuthObligationContract = (typeof AUTH_OBLIGATION_CONTRACTS)[number];
+/**
+ * Builds the canonical `<resourceId>:<contract>` obligation id for one
+ * guarded endpoint. Stable across runs (no clock, no randomness).
+ *
+ * Args:
+ *   resourceId: The detector-emitted resource id (`auth.<method>.<path>`).
+ *   contract: One of {@link AUTH_OBLIGATION_CONTRACTS}.
+ *
+ * Returns:
+ *   string: The `<resourceId>:<contract>` obligation id.
+ */
+export declare function obligationId(resourceId: string, contract: AuthObligationContract): string;
+//# sourceMappingURL=obligations.d.ts.map

package/dist/obligations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"obligations.d.ts","sourceRoot":"","sources":["../src/obligations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,yBAAyB,wIAM5B,CAAC;AAEX,yCAAyC;AACzC,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhF;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,sBAAsB,GAAG,MAAM,CAEzF"}

package/dist/obligations.js

@@ -0,0 +1,67 @@
+/**
+ * The auth pack obligation vocabulary.
+ *
+ * Every obligation id is `<resourceId>:<contract>` where `<resourceId>` is
+ * the stable id the detector emits for one guarded endpoint
+ * (`auth.<method>.<path>`) and `<contract>` is one of the names below.
+ *
+ * Contract grammar: `auth:<verb>` where interior colons are NOT legal
+ * (these contracts do not carry their own namespace segment). Trailing
+ * colons are rejected by `ContractNameSchema` upstream.
+ *
+ * Vocabulary rationale (per the pack brief):
+ *
+ * - `auth:role-allowed` — A request with an authenticated principal whose
+ *   role satisfies the endpoint's `roleRequirement` reaches the handler.
+ *   Verified by issuing the request with a valid token carrying the
+ *   required role; the handler MUST produce its declared success status
+ *   (200 / 303 / 201).
+ *
+ * - `auth:role-denied` — A request whose principal is authenticated but
+ *   LACKS the required role is rejected with 401/403 BEFORE any state
+ *   mutation. Verified by issuing the same request with a role that does
+ *   not satisfy `roleRequirement`; the response MUST be a denial status
+ *   and MUST NOT mutate persisted state (this obligation AND
+ *   `auth:denied-no-side-effect` together prove "deny is deny").
+ *
+ * - `auth:tenant-isolated` — A request whose tenant claim differs from
+ *   the tenant bound to the target entity is rejected (the endpoint's
+ *   `attributes.tenancy` is `tenant-bound`; the example server enforces
+ *   `req.user.tenantId === target.tenantId`). Verified by replaying the
+ *   admin request with the token of a different tenant; response is
+ *   denial status, no read or write succeeds.
+ *
+ * - `auth:denied-no-side-effect` — A denied request produces no persisted
+ *   side effect. Verified by: (a) asserting the denial status, then
+ *   (b) issuing a GET on the resource — the entity is unchanged from the
+ *   pre-denied snapshot. This is the "deny is deny, not pretend" check
+ *   that catches "200 OK with empty body" fake-greens.
+ *
+ * - `auth:forged-token-rejected` — A request carrying a token whose
+ *   signature does not validate (or whose payload fails verification)
+ *   is rejected with 401 and never reaches the handler. Verified by
+ *   mutating one byte of a valid token and asserting 401; the witness
+ *   GET shows the entity is untouched.
+ */
+export const AUTH_OBLIGATION_CONTRACTS = [
+    'auth:role-allowed',
+    'auth:role-denied',
+    'auth:tenant-isolated',
+    'auth:denied-no-side-effect',
+    'auth:forged-token-rejected',
+];
+/**
+ * Builds the canonical `<resourceId>:<contract>` obligation id for one
+ * guarded endpoint. Stable across runs (no clock, no randomness).
+ *
+ * Args:
+ *   resourceId: The detector-emitted resource id (`auth.<method>.<path>`).
+ *   contract: One of {@link AUTH_OBLIGATION_CONTRACTS}.
+ *
+ * Returns:
+ *   string: The `<resourceId>:<contract>` obligation id.
+ */
+export function obligationId(resourceId, contract) {
+    return `${resourceId}:${contract}`;
+}
+//# sourceMappingURL=obligations.js.map

package/dist/obligations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"obligations.js","sourceRoot":"","sources":["../src/obligations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,mBAAmB;IACnB,kBAAkB;IAClB,sBAAsB;IACtB,4BAA4B;IAC5B,4BAA4B;CACpB,CAAC;AAKX;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,UAAkB,EAAE,QAAgC;IAC/E,OAAO,GAAG,UAAU,IAAI,QAAQ,EAAE,CAAC;AACrC,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Pack identity constants. The GPP/3 handshake pins these values: the
+ * `.gateforge.yml` plugin entry MUST declare the same `id` and `version`.
+ */
+/** Plugin id every auth pack contribution is pinned to. */
+export declare const PACK_PLUGIN_ID = "gateforge.pack-auth";
+/** Detector/pack version; bumped on schema-changing changes. */
+export declare const PACK_VERSION = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,2DAA2D;AAC3D,eAAO,MAAM,cAAc,wBAAwB,CAAC;AAEpD,gEAAgE;AAChE,eAAO,MAAM,YAAY,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,9 @@
+/**
+ * Pack identity constants. The GPP/3 handshake pins these values: the
+ * `.gateforge.yml` plugin entry MUST declare the same `id` and `version`.
+ */
+/** Plugin id every auth pack contribution is pinned to. */
+export const PACK_PLUGIN_ID = 'gateforge.pack-auth';
+/** Detector/pack version; bumped on schema-changing changes. */
+export const PACK_VERSION = '0.1.0';
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,2DAA2D;AAC3D,MAAM,CAAC,MAAM,cAAc,GAAG,qBAAqB,CAAC;AAEpD,gEAAgE;AAChE,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC"}

package/examples/example.billing.refund.adapter.d.mts

@@ -0,0 +1,7 @@
+/**
+ * Type declaration for the shipped sample adapter. The .mjs file is
+ * dynamically loaded by the witness; for static type checking in the
+ * test suite, we declare its default export here.
+ */
+declare const sample: import('../src/adapter-schema.js').AuthEntityAdapter;
+export default sample;

package/examples/example.billing.refund.adapter.mjs

@@ -0,0 +1,104 @@
+/**
+ * Sample entity adapter for the gateforge auth example app
+ * (`example/auth/`): the `example.billing.refund` resource, read via
+ * `GET /api/billing/refund/:id`.
+ *
+ * DOCUMENTATION + SAMPLE ONLY — actual adapter loading is the engine
+ * side (witness registry, ADR 0002): adapters live in the project's
+ * `.gateforge/adapters/` directory as `<resourceId>.mjs` and are
+ * executed ENGINE-SIDE with GET-only transport. Copy this file to
+ * `.gateforge/adapters/example.billing.refund.mjs` in a project that
+ * runs the example auth app and the witness service can prove
+ * `example.billing.refund` persistence evidence for the
+ * `auth:denied-no-side-effect` obligation.
+ *
+ * Adapter contract (interface pin #8; the pack's
+ * `AuthEntityAdapterSchema`):
+ *   - `read(ctx, id)`  — GET-only fetch of one entity; never mutates.
+ *   - `normalize(body)` — project the raw body onto
+ *     `{ entityId, fields }` (fields carry the classified primaryKey
+ *     and the status / amount that prove "no side effect on deny").
+ *   - `deletion: 'hard'` — the auth example does NOT soft-delete
+ *     refunds; the only state change is the create itself.
+ *   - `environmentFingerprint` — the target-environment marker the
+ *     witness compares against a probe GET (GF-13): the example app
+ *     serves `x-gateforge-env: auth-loopback-v1` on every route once
+ *     wired for gateforge.
+ *   - `resourceId` — registry identity; must match the file name.
+ */
+
+/** Registry identity of the example billing-refund resource. */
+const RESOURCE_ID = 'example.billing.refund';
+
+/**
+ * The marker the witness expects on any probe/read response: the
+ * example app serves `x-gateforge-env: auth-loopback-v1` on every
+ * route.
+ */
+const ENVIRONMENT_FINGERPRINT = 'auth-loopback-v1';
+
+/**
+ * GET-only entity read against the example app's read API.
+ *
+ * Args:
+ *   ctx: Witness-provided context (loopback base URL; optional headers).
+ *   id: The entity id (`rfn-1`, ...).
+ *
+ * Returns:
+ *   Promise<unknown>: The raw refund object
+ *     `{ id, amount_cents, tenant_id, requested_by, status, created_at }`.
+ *
+ * Throws:
+ *   Error: On a fingerprint mismatch (environment attestation) or a
+ *     non-200/404 status. 404 surfaces as `null` — the entity is gone.
+ */
+async function read(ctx, id) {
+  const response = await fetch(`${ctx.baseUrl}/api/billing/refund/${encodeURIComponent(id)}`, {
+    headers: ctx.headers ?? {},
+  });
+  if (response.status === 404) {
+    return null;
+  }
+  if (!response.ok) {
+    throw new Error(`example billing adapter: GET /api/billing/refund/${id} -> ${response.status}`);
+  }
+  const marker = response.headers.get('x-gateforge-env');
+  if (marker !== ENVIRONMENT_FINGERPRINT) {
+    throw new Error(
+      `example billing adapter: environment fingerprint mismatch ` +
+        `(expected ${ENVIRONMENT_FINGERPRINT}, got ${JSON.stringify(marker)})`,
+    );
+  }
+  return response.json();
+}
+
+/**
+ * Projects the raw refund body onto the evidence shape.
+ *
+ * Args:
+ *   body: The raw refund object from `read`.
+ *
+ * Returns:
+ *   { entityId, fields }: The entity id plus the fields the
+ *     `auth:denied-no-side-effect` obligation compares against the
+ *     pre-deny snapshot.
+ */
+function normalize(body) {
+  return {
+    entityId: String(body.id),
+    fields: {
+      id: body.id,
+      amount_cents: body.amount_cents,
+      tenant_id: body.tenant_id,
+      status: body.status,
+    },
+  };
+}
+
+export default {
+  resourceId: RESOURCE_ID,
+  read,
+  normalize,
+  deletion: 'hard',
+  environmentFingerprint: ENVIRONMENT_FINGERPRINT,
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@gate-forge/pack-auth",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "description": "Authorization discovery pack: AST/heuristic detection of role guards, tenant scoping, and authentication enforcement in TypeScript/JavaScript HTTP routes; emits auth resource per guarded endpoint with roleRequirement + tenancy attributes; ships the auth obligation vocabulary (role-allowed/role-denied/tenant-isolated/denied-no-side-effect/forged-token-rejected).",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "README.md",
+    "dist",
+    "examples"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@gate-forge/core": "^0.1.0",
+    "@gate-forge/plugin-protocol": "^0.1.0",
+    "zod": "^4.1.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/umiddey/gateforge.git",
+    "directory": "packages/pack-auth"
+  },
+  "bugs": {
+    "url": "https://github.com/umiddey/gateforge/issues"
+  },
+  "homepage": "https://github.com/umiddey/gateforge#readme"
+}