@willyim/idp 0.1.1 → 0.3.0

package/dist/src/schemas/index.js

@@ -0,0 +1,207 @@
+/**
+ * The wire shapes of the IdP management API (`/api/v1/*`), as zod schemas.
+ *
+ * One definition, three consumers: `apps/idp` validates incoming requests with
+ * them, `scripts/generate-openapi.mjs` turns them into the OpenAPI document,
+ * and the SDK's `api.ts` parses responses against them. Types are `z.infer`,
+ * so there is no generated `.d.ts` to drift out of sync.
+ *
+ * The OIDC endpoints are NOT here — those are standards-defined and live in
+ * `../wire.ts`, next to the code that talks to them.
+ */
+import { z } from "zod";
+export const ApplicationSchema = z.object({
+    clientId: z.string(),
+    name: z.string().nullable(),
+    app: z.string().nullable().describe("Application key; consumer workspace claims are filtered by this"),
+    allowSignup: z.boolean().describe("Whether unknown users may sign themselves up"),
+    permissions: z.array(z.string()).describe("The app's declared product-permission catalog"),
+    redirectUris: z.array(z.string()),
+    disabled: z.boolean(),
+    createdAt: z.string().describe("ISO 8601 timestamp"),
+});
+export const UserSchema = z.object({
+    id: z.string(),
+    email: z.string(),
+    name: z.string().nullable(),
+    emailVerified: z.boolean(),
+    createdAt: z.string(),
+});
+export const WorkspaceSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    slug: z.string(),
+    applicationId: z.string().nullable(),
+    createdAt: z.string(),
+});
+export const ApplicationListSchema = z.object({ applications: z.array(ApplicationSchema) });
+/**
+ * Register an application. Superadmin only — there is no app to scope it to
+ * yet, so no per-app permission could authorize it.
+ */
+export const CreateApplicationInput = z.object({
+    name: z.string().min(1),
+    app: z
+        .string()
+        .min(1)
+        .regex(/^[a-z0-9][a-z0-9-]*$/, "lowercase letters, numbers and dashes only")
+        .describe("Stable application key — the join key for members, workspaces and keys"),
+    redirectUris: z.array(z.string().min(1)).min(1),
+    firstAdminUserId: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Who becomes the app's first IdP admin. Defaults to the calling user; null leaves the app with no members (superadmin-managed)."),
+});
+export const ApplicationCreatedSchema = z.object({
+    clientId: z.string(),
+    clientSecret: z.string().describe("Plaintext client secret — shown exactly once, never stored"),
+    app: z.string(),
+});
+/** Partial update of an application. Omitted fields are left alone. */
+export const UpdateApplicationInput = z.object({
+    name: z.string().min(1).optional(),
+    redirectUris: z.array(z.string().min(1)).min(1).optional(),
+    allowSignup: z.boolean().optional(),
+});
+export const ClientSecretSchema = z.object({
+    clientSecret: z.string().describe("Plaintext client secret — shown exactly once, never stored"),
+});
+/** Replaces the app's product-permission catalog wholesale. */
+export const SetAppPermissionsInput = z.object({
+    permissions: z.array(z.string().min(1)),
+});
+export const AppPermissionsSchema = z.object({ permissions: z.array(z.string()) });
+export const UserListSchema = z.object({ users: z.array(UserSchema) });
+export const WorkspaceListSchema = z.object({ workspaces: z.array(WorkspaceSchema) });
+// --- Write management API (scoped-key authenticated, per-app) ---
+export const RoleSchema = z.enum(["admin", "member"]);
+export const MemberSchema = z.object({
+    userId: z.string(),
+    email: z.string(),
+    name: z.string().nullable(),
+    role: RoleSchema,
+    permissions: z.array(z.string()),
+});
+export const MemberListSchema = z.object({ members: z.array(MemberSchema) });
+/** Add (existing user) or invite (new email) an app member. */
+export const InviteMemberInput = z.object({
+    email: z.string().email(),
+    role: RoleSchema.default("member"),
+    permissions: z.array(z.string()).default([]),
+});
+export const InviteMemberResult = z.object({
+    // "added" = existing user joined now; "invited" = pending invite emailed.
+    result: z.enum(["added", "invited"]),
+});
+export const UpdateMemberInput = z.object({
+    role: RoleSchema,
+    permissions: z.array(z.string()).default([]),
+});
+export const CreateWorkspaceInput = z.object({
+    name: z.string().min(1),
+    slug: z
+        .string()
+        .min(1)
+        .regex(/^[a-z0-9-]+$/, "lowercase letters, numbers and dashes only"),
+});
+export const WorkspaceCreatedSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    slug: z.string(),
+});
+export const OkSchema = z.object({ ok: z.literal(true) });
+// --- End-user API keys (the app's own API credentials, stored in the IdP) ---
+export const UserApiKeySchema = z.object({
+    id: z.string(),
+    userId: z.string(),
+    workspaceId: z.string().nullable(),
+    name: z.string(),
+    prefix: z.string().describe("Non-secret token prefix (wak_…) for display"),
+    scopes: z.array(z.string()),
+    status: z.enum(["active", "expired", "revoked"]),
+    createdAt: z.string(),
+    lastUsedAt: z.string().nullable(),
+    expiresAt: z.string().nullable(),
+});
+export const UserApiKeyListSchema = z.object({ keys: z.array(UserApiKeySchema) });
+export const CreateUserApiKeyInput = z.object({
+    userId: z.string().min(1),
+    name: z.string().min(1),
+    scopes: z.array(z.string()).default([]).describe("Subset of the app's product permission catalog"),
+    workspaceId: z.string().optional(),
+    expiresAt: z.iso.datetime().optional().describe("ISO 8601; omit for non-expiring"),
+});
+export const UserApiKeyCreatedSchema = z.object({
+    id: z.string(),
+    token: z.string().describe("Plaintext key — shown exactly once, never stored"),
+    prefix: z.string(),
+});
+export const ValidateUserApiKeyInput = z.object({ token: z.string().min(1) });
+export const UserApiKeyValidationSchema = z.union([
+    z.object({
+        valid: z.literal(true),
+        keyId: z.string(),
+        userId: z.string(),
+        workspaceId: z.string().nullable(),
+        scopes: z.array(z.string()),
+        name: z.string(),
+    }),
+    z.object({ valid: z.literal(false), reason: z.enum(["not_found", "revoked", "expired"]) }),
+]);
+export const AuditEntrySchema = z.object({
+    id: z.number(),
+    tableName: z.string(),
+    operation: z.string(),
+    rowId: z.string().nullable(),
+    userId: z.string().nullable(),
+    actor: z.string().nullable(),
+    createdAt: z.string(),
+});
+export const AuditListSchema = z.object({ entries: z.array(AuditEntrySchema) });
+// --- Scoped management API keys (drive this API for one app) ---
+export const ApiKeySchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    prefix: z.string().describe("Non-secret token prefix (wim_…) for display"),
+    permissions: z.array(z.string()).describe("IdP management permissions this key holds"),
+    status: z.enum(["active", "expired", "revoked"]),
+    createdAt: z.string(),
+    lastUsedAt: z.string().nullable(),
+    expiresAt: z.string().nullable(),
+    revokedAt: z.string().nullable(),
+});
+export const ApiKeyListSchema = z.object({ keys: z.array(ApiKeySchema) });
+export const CreateApiKeyInput = z.object({
+    name: z.string().min(1),
+    permissions: z
+        .array(z.string().min(1))
+        .describe("IdP management permissions; must be a subset of the caller's own on this app"),
+    expiresAt: z.iso.datetime().optional().describe("ISO 8601; omit for non-expiring"),
+});
+export const ApiKeyCreatedSchema = z.object({
+    id: z.string(),
+    token: z.string().describe("Plaintext key — shown exactly once, never stored"),
+    prefix: z.string(),
+});
+// --- IdP-level admin keys (superadmin over every app) ---
+export const AdminKeySchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    prefix: z.string().describe("Non-secret token prefix (wim_…) for display"),
+    status: z.enum(["active", "expired", "revoked"]),
+    createdAt: z.string(),
+    lastUsedAt: z.string().nullable(),
+    expiresAt: z.string().nullable(),
+    revokedAt: z.string().nullable(),
+});
+export const AdminKeyListSchema = z.object({ keys: z.array(AdminKeySchema) });
+export const CreateAdminKeyInput = z.object({
+    name: z.string().min(1).describe("Who holds it — one key per agent, so the audit log reads"),
+    expiresAt: z.iso.datetime().optional().describe("ISO 8601; omit for non-expiring"),
+});
+export const AdminKeyCreatedSchema = z.object({
+    id: z.string(),
+    token: z.string().describe("Plaintext key — shown exactly once, never stored"),
+    prefix: z.string(),
+});

package/dist/src/schemas/openapi.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The published OpenAPI document, built from `./operations.ts`.
+ *
+ * `apps/idp` serves this at `/api/v1/openapi.json`; `npm run openapi` writes
+ * the same object to `openapi/idp-api.json` so the snapshot in the repo is
+ * always what the server would answer.
+ */
+export declare function buildOpenApiDocument(input: {
+    baseUrl: string;
+}): {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+        description: string;
+    };
+    servers: {
+        url: string;
+    }[];
+    components: {
+        securitySchemes: {
+            bearerAuth: {
+                type: string;
+                scheme: string;
+                description: string;
+            };
+        };
+    };
+    paths: Record<string, Record<string, unknown>>;
+};
+//# sourceMappingURL=openapi.d.ts.map

package/dist/src/schemas/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../../src/schemas/openapi.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAqFH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;;;;;;;;;;;EA6B9D"}

package/dist/src/schemas/openapi.js

@@ -0,0 +1,111 @@
+/**
+ * The published OpenAPI document, built from `./operations.ts`.
+ *
+ * `apps/idp` serves this at `/api/v1/openapi.json`; `npm run openapi` writes
+ * the same object to `openapi/idp-api.json` so the snapshot in the repo is
+ * always what the server would answer.
+ */
+import { z } from "zod";
+import { lookup, operations } from "./operations.js";
+/**
+ * Responses describe what the API *returns*, so they use zod's output types.
+ * Request bodies describe what a caller may *send*, which is a different shape:
+ * a field with a `.default()` is optional on the way in and guaranteed on the
+ * way out. Emitting output types for both would mark every defaulted field
+ * `required` and force callers to supply values the API would have defaulted.
+ */
+const json = (schema) => z.toJSONSchema(schema);
+const jsonInput = (schema) => z.toJSONSchema(schema, { io: "input" });
+const DESCRIPTION = "Management API for the willy.im identity provider. Authenticate with `Authorization: Bearer <token>`. Two kinds of token: the superadmin `ADMIN_API_TOKEN` (every app) and per-app **scoped API keys** minted in the admin console (one app, a fixed permission set). The cross-app endpoints below require the superadmin token.";
+function pathParamNames(path) {
+    return [...path.matchAll(/\{([^}]+)\}/g)].map((match) => match[1]);
+}
+function parametersFor(path, def) {
+    const pathParams = pathParamNames(path).map((name) => ({
+        name,
+        in: "path",
+        required: true,
+        ...(def.params?.[name] ? { description: def.params[name] } : {}),
+        schema: { type: "string" },
+    }));
+    const queryParams = (def.query ?? []).map((param) => ({
+        name: param.name,
+        in: "query",
+        required: param.required ?? false,
+        ...(param.description ? { description: param.description } : {}),
+        schema: { type: "string" },
+    }));
+    return [...pathParams, ...queryParams];
+}
+function operationObject(method, path, def) {
+    const scoped = def.permission !== undefined;
+    const write = method !== "get";
+    const parameters = parametersFor(path, def);
+    return {
+        summary: def.summary,
+        description: def.description ??
+            (scoped
+                ? `Requires \`${def.permission}\` on the path app (or the superadmin token).`
+                : "Requires the superadmin token."),
+        security: [{ bearerAuth: [] }],
+        ...(parameters.length ? { parameters } : {}),
+        ...(def.input
+            ? {
+                requestBody: {
+                    required: true,
+                    content: { "application/json": { schema: jsonInput(def.input) } },
+                },
+            }
+            : {}),
+        responses: {
+            [def.successCode]: {
+                description: "OK",
+                content: { "application/json": { schema: json(def.success) } },
+            },
+            "401": { description: "Missing or invalid bearer token" },
+            ...(scoped
+                ? { "403": { description: "Key lacks the permission / is bound to another app" } }
+                : {}),
+            ...(write
+                ? {
+                    "405": {
+                        description: "Method not allowed on this resource (see the `Allow` header)",
+                    },
+                    "409": { description: "Conflict (already a member, last admin, slug taken, …)" },
+                }
+                : {}),
+            ...(def.notFound ? { "404": { description: def.notFound } } : {}),
+            ...(def.input ? { "422": { description: "Body failed validation" } } : {}),
+        },
+    };
+}
+export function buildOpenApiDocument(input) {
+    const paths = {};
+    for (const key of Object.keys(operations)) {
+        const [method, path] = key.split(" ");
+        const def = lookup(method, path);
+        if (!def)
+            continue;
+        paths[path] ??= {};
+        paths[path][method] = operationObject(method, path, def);
+    }
+    return {
+        openapi: "3.1.0",
+        info: {
+            title: "willy.im IdP — Management API",
+            version: "1.0.0",
+            description: DESCRIPTION,
+        },
+        servers: [{ url: input.baseUrl }],
+        components: {
+            securitySchemes: {
+                bearerAuth: {
+                    type: "http",
+                    scheme: "bearer",
+                    description: "Superadmin ADMIN_API_TOKEN or a scoped API key (wim_…).",
+                },
+            },
+        },
+        paths,
+    };
+}