@gnldev/auth 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The authenticated subject. The free tier only uses `roles`; the `permissions`/`orgId` fields are
+ * ALREADY reserved for EE (fine-grained RBAC + multi-organization) → the schema won't break later.
+ */
+export interface Principal {
+    id?: string;
+    /**
+     * WHICH CREDENTIAL spoke, never WHO — the two are different questions and this field exists because
+     * one field could not answer both.
+     *
+     * `id` is a SUBJECT: it answers "whose data is this", and `resolveResourceId`
+     * (packages/server/src/index.ts) hands it straight to the memory layer as `ThreadRecord.resourceId`,
+     * overriding any subject the request named. `credentialId` is a BUDGET KEY: it answers "who is
+     * spending", and is safe to synthesize precisely because nothing reads it as an owner.
+     *
+     * Measured, which is why the separation is enforced rather than advised: filling `id` with a token
+     * fingerprint made `resolveResourceId` return that fingerprint for a caller that had explicitly sent
+     * `resourceId: 'user-42'`, collapsing `user-42` and `user-99` into ONE bucket with no error — the
+     * shared-bucket regression that function's own comment records as measured and fixed, and a silent
+     * drop where its stated rule is "an INVALID value is a 400, not a silent drop".
+     *
+     * So: rate limiting, admission control and quota accounting may key on this. Memory scoping,
+     * ownership and access-control decisions MUST NOT — for those, an absent `id` means the deployment
+     * genuinely has no per-caller identity, and that absence is load-bearing information.
+     */
+    credentialId?: string;
+    roles: string[];
+    /** The field name identifying an organization — auth-ee/server/studio and stored records use this name. */
+    orgId?: string;
+    permissions?: string[];
+    [k: string]: unknown;
+}
+/** Description of what's being accessed — the provider can decide based on path/method/action/resource. */
+export interface AuthContext {
+    path: string;
+    method: string;
+    action: 'read' | 'write';
+    resource?: string;
+    /**
+     * EE fine-grained permission (e.g. 'agents:run', 'users:write'). Set by the gate's `allowP`. When
+     * present, an RBAC provider matches THIS exact permission instead of deriving one from resource/action
+     * (see @gnldev/auth-ee rbac.ts `requiredPermission`). A free/read-write provider ignores it and falls back
+     * to `action` (the gate already reduces the permission to read/write) → coarse but backward-compatible.
+     */
+    permission?: string;
+}
+/** The authorization decision. A denial carries `status` (401 identity / 403 authorization) + an optional reason. */
+export type Decision = {
+    allow: true;
+} | {
+    allow: false;
+    status?: 401 | 403;
+    reason?: string;
+};
+/** Capabilities declared by the provider → studio `/capabilities` → opens premium UI surfaces. */
+export interface AuthCapabilities {
+    sso: boolean;
+    rbac: boolean;
+    audit: boolean;
+    multiOrganization: boolean;
+    users: boolean;
+    /** EE: license plan name ('pro'/'enterprise'/'dev') — UI badge. Not present in the free tier. */
+    plan?: string;
+    /** EE: license expiry (epoch ms) — UI expiry warning. Not present when unlimited/free. */
+    licenseExp?: number;
+}
+/**
+ * Auth provider contract. The host (server/studio) calls `authenticate` first, then `authorize`.
+ * `capabilities` is optional (the free tier declares all of them false).
+ */
+export interface AuthProvider {
+    authenticate(req: Request): Promise<Principal | null> | Principal | null;
+    authorize(principal: Principal | null, req: Request, ctx: AuthContext): Promise<Decision> | Decision;
+    capabilities?(): Partial<AuthCapabilities>;
+    /**
+     * `false` declares that this provider has NO principal model — `authenticate()` returns null for
+     * every request, by construction, not because a token was missing. Hosts that scope organizations
+     * by identity reject that combination instead of letting a header pick the scope. Omit it (the
+     * normal case): a provider that can authenticate needs to say nothing. See `bindsIdentity()`.
+     */
+    bindsIdentity?: boolean;
+}
+/**
+ * Credentials for a single role: bearer token and/or basic user+pass. If `orgId` is given, the
+ * identity is BOUND to that organization: hosts (server/studio) derive the organization scope from
+ * the principal instead of the header; a different `x-gnl-org` request gets a 403 (organization
+ * isolation is enforced by identity, it cannot be spoofed).
+ */
+export type Cred = {
+    token?: string;
+    user?: string;
+    pass?: string;
+    orgId?: string;
+    /**
+     * EXPLICIT platform-admin grant (scope: 'platform') — see @gnldev/auth scope.ts. Injects the reserved
+     * `platform-admin` role into the principal. Use it to bootstrap a statically-configured root admin
+     * that the strict (EE multi-org) model must recognise as cross-org; WITHOUT it, an unbound identity
+     * is denied under the strict model (fail-closed). Harmless in the free tier (the role is inert there).
+     */
+    platformAdmin?: boolean;
+};

package/dist/types.js

@@ -0,0 +1,4 @@
+// @gnldev/auth — stable auth contract. The free core defines this; @gnldev/auth-ee (paid) implements the
+// same interface → premium (RBAC/SSO/multi-organization/audit) plugs in without touching the core.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,yGAAyG;AACzG,mGAAmG","sourcesContent":["// @gnldev/auth — stable auth contract. The free core defines this; @gnldev/auth-ee (paid) implements the\n// same interface → premium (RBAC/SSO/multi-organization/audit) plugs in without touching the core.\n\n/**\n * The authenticated subject. The free tier only uses `roles`; the `permissions`/`orgId` fields are\n * ALREADY reserved for EE (fine-grained RBAC + multi-organization) → the schema won't break later.\n */\nexport interface Principal {\n  id?: string;\n  /**\n   * WHICH CREDENTIAL spoke, never WHO — the two are different questions and this field exists because\n   * one field could not answer both.\n   *\n   * `id` is a SUBJECT: it answers \"whose data is this\", and `resolveResourceId`\n   * (packages/server/src/index.ts) hands it straight to the memory layer as `ThreadRecord.resourceId`,\n   * overriding any subject the request named. `credentialId` is a BUDGET KEY: it answers \"who is\n   * spending\", and is safe to synthesize precisely because nothing reads it as an owner.\n   *\n   * Measured, which is why the separation is enforced rather than advised: filling `id` with a token\n   * fingerprint made `resolveResourceId` return that fingerprint for a caller that had explicitly sent\n   * `resourceId: 'user-42'`, collapsing `user-42` and `user-99` into ONE bucket with no error — the\n   * shared-bucket regression that function's own comment records as measured and fixed, and a silent\n   * drop where its stated rule is \"an INVALID value is a 400, not a silent drop\".\n   *\n   * So: rate limiting, admission control and quota accounting may key on this. Memory scoping,\n   * ownership and access-control decisions MUST NOT — for those, an absent `id` means the deployment\n   * genuinely has no per-caller identity, and that absence is load-bearing information.\n   */\n  credentialId?: string;\n  roles: string[];\n  /** The field name identifying an organization — auth-ee/server/studio and stored records use this name. */\n  orgId?: string;\n  permissions?: string[];\n  [k: string]: unknown;\n}\n\n/** Description of what's being accessed — the provider can decide based on path/method/action/resource. */\nexport interface AuthContext {\n  path: string;\n  method: string;\n  action: 'read' | 'write';\n  resource?: string;\n  /**\n   * EE fine-grained permission (e.g. 'agents:run', 'users:write'). Set by the gate's `allowP`. When\n   * present, an RBAC provider matches THIS exact permission instead of deriving one from resource/action\n   * (see @gnldev/auth-ee rbac.ts `requiredPermission`). A free/read-write provider ignores it and falls back\n   * to `action` (the gate already reduces the permission to read/write) → coarse but backward-compatible.\n   */\n  permission?: string;\n}\n\n/** The authorization decision. A denial carries `status` (401 identity / 403 authorization) + an optional reason. */\nexport type Decision = { allow: true } | { allow: false; status?: 401 | 403; reason?: string };\n\n/** Capabilities declared by the provider → studio `/capabilities` → opens premium UI surfaces. */\nexport interface AuthCapabilities {\n  sso: boolean;\n  rbac: boolean;\n  audit: boolean;\n  multiOrganization: boolean;\n  users: boolean;\n  /** EE: license plan name ('pro'/'enterprise'/'dev') — UI badge. Not present in the free tier. */\n  plan?: string;\n  /** EE: license expiry (epoch ms) — UI expiry warning. Not present when unlimited/free. */\n  licenseExp?: number;\n}\n\n/**\n * Auth provider contract. The host (server/studio) calls `authenticate` first, then `authorize`.\n * `capabilities` is optional (the free tier declares all of them false).\n */\nexport interface AuthProvider {\n  authenticate(req: Request): Promise<Principal | null> | Principal | null;\n  authorize(principal: Principal | null, req: Request, ctx: AuthContext): Promise<Decision> | Decision;\n  capabilities?(): Partial<AuthCapabilities>;\n  /**\n   * `false` declares that this provider has NO principal model — `authenticate()` returns null for\n   * every request, by construction, not because a token was missing. Hosts that scope organizations\n   * by identity reject that combination instead of letting a header pick the scope. Omit it (the\n   * normal case): a provider that can authenticate needs to say nothing. See `bindsIdentity()`.\n   */\n  bindsIdentity?: boolean;\n}\n\n/**\n * Credentials for a single role: bearer token and/or basic user+pass. If `orgId` is given, the\n * identity is BOUND to that organization: hosts (server/studio) derive the organization scope from\n * the principal instead of the header; a different `x-gnl-org` request gets a 403 (organization\n * isolation is enforced by identity, it cannot be spoofed).\n */\nexport type Cred = {\n  token?: string;\n  user?: string;\n  pass?: string;\n  orgId?: string;\n  /**\n   * EXPLICIT platform-admin grant (scope: 'platform') — see @gnldev/auth scope.ts. Injects the reserved\n   * `platform-admin` role into the principal. Use it to bootstrap a statically-configured root admin\n   * that the strict (EE multi-org) model must recognise as cross-org; WITHOUT it, an unbound identity\n   * is denied under the strict model (fail-closed). Harmless in the free tier (the role is inert there).\n   */\n  platformAdmin?: boolean;\n};\n"]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@gnldev/auth",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "description": "Auth contract (AuthProvider) + free role-based default (bearer/basic, read/write). Open-core seam: @gnldev/auth-ee plugs into the same interface.",
+  "keywords": [
+    "ai",
+    "agent",
+    "llm",
+    "typescript",
+    "ai-sdk",
+    "durable",
+    "exactly-once",
+    "authentication",
+    "rbac",
+    "api-keys"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "hono": "^4.6.0"
+  },
+  "devDependencies": {
+    "hono": "^4.13.2"
+  },
+  "author": "Karaca Yılmaz (https://gnl.dev)",
+  "homepage": "https://gnl.dev",
+  "bugs": {
+    "url": "https://github.com/Karaca7/gnldev/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Karaca7/gnldev.git",
+    "directory": "packages/auth"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}