@agentage/identity 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentage Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# @agentage/identity
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The identity client for an agentage browser page: sign in at auth, a one-day token for the
+parts, sign out. It runs in the page and talks to auth with credentialed requests.
+
+```ts
+import { createIdentity } from '@agentage/identity';
+
+const id = createIdentity({
+  authUrl: 'https://auth.agentage.io',
+  audience: 'next.agentage.io',
+  scopes: ['probe:read'],
+});
+
+await id.signIn(); // auth's sign-in page, then back to this page
+const token = id.token(); // a TokenSource for createBridge({ token })
+await id.signOut(); // revokes the token, then ends the session
+```
+
+- `signIn()` resolves with the account when a session exists. Without one, the page goes to
+  `<authUrl>/sign-in?next=<this page>` and comes back after sign-in; call `signIn()` again on load.
+- `token()` returns `() => Promise<string | undefined>`. The first call mints a one-day PAT
+  (`POST /account/pat`, `format: 'jwt'`, label `browser`); it stays in page memory only and is
+  minted again after it expires. Without a session it gives `undefined`.
+- `signOut()` deletes that PAT (`DELETE /account/pat/{id}`; the parts refuse it within 60 s),
+  then ends the auth session.
+- `account()` is the signed-in account or `null`; `tokens()` lists the account's PATs.
+
+Auth needs at least one scope to mint, so pass `scopes`. `audience` is sent with the mint; auth
+derives the audience itself today. A failed call throws an `IdentityError` with `code`,
+`message` and the HTTP `status`. The client never logs a token.

package/dist/auth.d.ts

@@ -0,0 +1,58 @@
+import * as z from 'zod/mini';
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export type IdentityError = Error & {
+    code: string;
+    status: number;
+};
+declare const User: z.ZodMiniObject<{
+    id: z.ZodMiniString<string>;
+    email: z.ZodMiniString<string>;
+    name: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniString<string>>>;
+}, z.core.$strip>;
+declare const Minted: z.ZodMiniObject<{
+    success: z.ZodMiniLiteral<true>;
+    data: z.ZodMiniObject<{
+        id: z.ZodMiniString<string>;
+        token: z.ZodMiniString<string>;
+        expiresAt: z.ZodMiniString<string>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+declare const Summary: z.ZodMiniObject<{
+    createdAt: z.ZodMiniNullable<z.ZodMiniString<string>>;
+    expiresAt: z.ZodMiniNullable<z.ZodMiniString<string>>;
+    id: z.ZodMiniString<string>;
+    label: z.ZodMiniString<string>;
+    scopes: z.ZodMiniArray<z.ZodMiniString<string>>;
+}, z.core.$strip>;
+export type Account = z.infer<typeof User>;
+export type MintedPat = z.infer<typeof Minted>['data'];
+export type TokenSummary = z.infer<typeof Summary>;
+export declare const authCalls: (authUrl: string, fetchFn: FetchLike) => {
+    account: () => Promise<{
+        id: string;
+        email: string;
+        name?: string | null | undefined;
+    } | null>;
+    mint: (body: object) => Promise<{
+        id: string;
+        token: string;
+        expiresAt: string;
+    }>;
+    list: () => Promise<{
+        createdAt: string | null;
+        expiresAt: string | null;
+        id: string;
+        label: string;
+        scopes: string[];
+    }[]>;
+    revoke: (id: string) => Promise<{
+        success: true;
+        data: {
+            revoked: true;
+        };
+    }>;
+    end: () => Promise<{
+        success: true;
+    }>;
+};
+export {};

package/dist/auth.js

@@ -0,0 +1,42 @@
+import * as z from 'zod/mini';
+const fail = ({ code, message }, status = 0) => Object.assign(new Error(message), { name: 'IdentityError', code, status });
+const unreachable = (path) => () => Promise.reject(fail({ code: 'NETWORK', message: `auth unreachable: ${path}` }));
+const ok = (data) => z.object({ success: z.literal(true), data });
+const str = z.string();
+const Failed = z.object({ error: z.object({ code: str, message: str }) });
+const User = z.object({ id: str, email: str, name: z.optional(z.nullable(str)) });
+const Minted = ok(z.object({ id: str, token: str, expiresAt: str }));
+const Times = { createdAt: z.nullable(str), expiresAt: z.nullable(str) };
+const Revoked = ok(z.object({ revoked: z.literal(true) }));
+const Summary = z.object({ id: str, label: str, scopes: z.array(str), ...Times });
+// One credentialed call to auth: the body parsed by `schema`, else a typed error.
+const caller = (authUrl, fetchFn) => async (schema, path, init = {}) => {
+    const sent = { ...init, credentials: 'include' };
+    const res = await fetchFn(`${authUrl}${path}`, sent).catch(unreachable(path));
+    const body = await res.json().catch(() => undefined);
+    const parsed = schema.safeParse(body);
+    if (res.ok && parsed.success)
+        return parsed.data;
+    const plain = { code: `HTTP_${res.status}`, message: `${path} answered ${res.status}` };
+    throw fail(Failed.safeParse(body).data?.error ?? plain, res.status);
+};
+const JSON_TYPE = { 'content-type': 'application/json' };
+const SIGN_OUT = { method: 'POST', headers: JSON_TYPE, body: '{}' };
+// auth's REST: the session by cookie, the PAT routes by a short-lived session JWT.
+export const authCalls = (authUrl, fetchFn) => {
+    const call = caller(authUrl, fetchFn);
+    const pat = async (schema, path, method, body) => {
+        const { token } = await call(z.object({ token: str }), '/api/auth/token');
+        const headers = { ...JSON_TYPE, authorization: `Bearer ${token}` };
+        return call(schema, `/account/pat${path}`, { method, headers, body: JSON.stringify(body) });
+    };
+    const session = z.nullable(z.object({ user: User }));
+    return {
+        // get-session answers 200 and null when nobody is signed in.
+        account: async () => (await call(session, '/api/auth/get-session'))?.user ?? null,
+        mint: async (body) => (await pat(Minted, '', 'POST', body)).data,
+        list: async () => (await pat(ok(z.array(Summary)), '', 'GET')).data,
+        revoke: (id) => pat(Revoked, `/${encodeURIComponent(id)}`, 'DELETE'),
+        end: () => call(z.object({ success: z.literal(true) }), '/api/auth/sign-out', SIGN_OUT),
+    };
+};

package/dist/identity.d.ts

@@ -0,0 +1,33 @@
+import { type FetchLike } from './auth.js';
+export type TokenSource = () => Promise<string | undefined>;
+export type Identity = ReturnType<typeof createIdentity>;
+type Nav = Pick<Location, 'href' | 'assign'>;
+export interface IdentityOptions {
+    authUrl: string;
+    audience: string;
+    scopes?: string[];
+    fetch?: FetchLike;
+    location?: Nav;
+}
+export declare const createIdentity: (options: IdentityOptions) => {
+    account: () => Promise<{
+        id: string;
+        email: string;
+        name?: string | null | undefined;
+    } | null>;
+    signIn: () => Promise<{
+        id: string;
+        email: string;
+        name?: string | null | undefined;
+    }>;
+    token: () => TokenSource;
+    tokens: () => Promise<{
+        createdAt: string | null;
+        expiresAt: string | null;
+        id: string;
+        label: string;
+        scopes: string[];
+    }[]>;
+    signOut: () => Promise<void>;
+};
+export {};

package/dist/identity.js

@@ -0,0 +1,65 @@
+import { authCalls } from './auth.js';
+// A token this close to its expiry is minted again, so a call never carries a dying one.
+const SKEW_MS = 60_000;
+const DAY_MS = 86_400_000;
+// From the local mint time, so a client clock off from auth's cannot force a mint per call.
+const deadline = (pat, startedAt) => {
+    const life = Date.parse(pat.expiresAt) - startedAt;
+    return startedAt + (life > SKEW_MS ? Math.min(life, DAY_MS) : DAY_MS) - SKEW_MS;
+};
+// The PAT lives in page memory only: one mint in flight, again once it expires.
+const tokenCache = (renew) => {
+    let held;
+    let minting;
+    const mint = async () => {
+        const startedAt = Date.now();
+        const pat = await renew();
+        held = pat && { pat, until: deadline(pat, startedAt) };
+    };
+    const current = async () => {
+        if (!held || held.until <= Date.now())
+            await (minting ??= mint().finally(() => (minting = undefined)));
+        return held?.pat.token;
+    };
+    // A mint in flight lands first, so its PAT is revoked too.
+    const release = async (revoke) => {
+        await minting?.catch(() => undefined);
+        const last = held;
+        held = undefined;
+        if (last)
+            await revoke(last.pat.id);
+    };
+    return { current, release };
+};
+// Signed in: resolves now. Else the page leaves for auth's sign-in and comes back to `next`.
+const signIn = async (auth, authUrl, nav) => {
+    const signedIn = await auth.account();
+    if (signedIn)
+        return signedIn;
+    const page = nav ?? globalThis.location;
+    page.assign(`${authUrl}/sign-in?next=${encodeURIComponent(page.href)}`);
+    return new Promise(() => undefined);
+};
+// The session ends even when the revoke fails; the failure still reaches the caller.
+const signOut = async (auth, cache) => {
+    try {
+        await cache.release(auth.revoke);
+    }
+    finally {
+        await auth.end();
+    }
+};
+export const createIdentity = (options) => {
+    const authUrl = options.authUrl.replace(/\/+$/, '');
+    const auth = authCalls(authUrl, options.fetch ?? ((url, init) => fetch(url, init)));
+    const { scopes, audience } = options;
+    const body = { format: 'jwt', label: 'browser', expiresInDays: 1, scopes, audience };
+    const cache = tokenCache(async () => ((await auth.account()) ? auth.mint(body) : undefined));
+    return {
+        account: auth.account,
+        signIn: () => signIn(auth, authUrl, options.location),
+        token: () => cache.current,
+        tokens: auth.list,
+        signOut: () => signOut(auth, cache),
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './identity.js';
+export type { Account, FetchLike, IdentityError, TokenSummary } from './auth.js';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './identity.js';

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@agentage/identity",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The agentage identity client for browser pages: sign in at auth, a one-day token for the parts, sign out",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentage/platform.git",
+    "directory": "packages/identity"
+  },
+  "homepage": "https://agentage.io",
+  "bugs": {
+    "url": "https://github.com/agentage/platform/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "verify": "npm run verify --prefix ../..",
+    "prepublishOnly": "npm run verify"
+  },
+  "dependencies": {
+    "zod": "^4.2.0"
+  },
+  "keywords": [
+    "agentage",
+    "extension",
+    "identity"
+  ]
+}