@dakkitor/api-contracts 1.5.0 → 1.6.0

package/dist/relay-pods/relay-pods.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-pods.contract.d.ts","sourceRoot":"","sources":["../../contracts/relay-pods/relay-pods.contract.ts"],"names":[],"mappings":"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"}

package/dist/relay-pods/relay-pods.contract.js

@@ -0,0 +1,188 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.relayPodsContract = exports.AuthorizeRelayPodResponseSchema = exports.AuthorizeRelayPodBodySchema = exports.RelayPodReturnPathSchema = exports.CreateRelayPodCredentialBodySchema = exports.UpdateRelayPodBodySchema = exports.CreateRelayPodBodySchema = void 0;
+const core_1 = require("@ts-rest/core");
+const zod_1 = require("zod");
+const error_schemas_1 = require("../common/error-schemas");
+const relay_pods_schemas_1 = require("./relay-pods.schemas");
+__exportStar(require("./relay-pods.schemas"), exports);
+const c = (0, core_1.initContract)();
+const RelayPodSlugSchema = zod_1.z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/);
+const RelayPodDisplayNameSchema = zod_1.z.string().min(1).max(100);
+const RelayPodHttpsUrlSchema = zod_1.z
+    .string()
+    .url()
+    .refine((url) => new URL(url).protocol === 'https:', {
+    message: 'Relay pod URLs must use HTTPS',
+});
+exports.CreateRelayPodBodySchema = zod_1.z
+    .object({
+    slug: RelayPodSlugSchema,
+    displayName: RelayPodDisplayNameSchema,
+    ownerUserId: zod_1.z.string().uuid(),
+    publicBaseUrl: RelayPodHttpsUrlSchema,
+    status: relay_pods_schemas_1.RelayPodStatusSchema.optional(),
+})
+    .strict();
+exports.UpdateRelayPodBodySchema = zod_1.z
+    .object({
+    displayName: RelayPodDisplayNameSchema.optional(),
+    ownerUserId: zod_1.z.string().uuid().optional(),
+    publicBaseUrl: RelayPodHttpsUrlSchema.optional(),
+    status: relay_pods_schemas_1.RelayPodStatusSchema.optional(),
+    force: zod_1.z.boolean().optional(),
+})
+    .strict();
+exports.CreateRelayPodCredentialBodySchema = zod_1.z
+    .object({
+    expiresAt: zod_1.z.string().datetime().nullable().optional(),
+})
+    .strict();
+function isSafeRelayReturnPath(returnPath) {
+    let decoded = returnPath;
+    for (let depth = 0; depth < 4; depth += 1) {
+        if (!/^\/(?!\/)/.test(decoded) || decoded.includes('\\')) {
+            return false;
+        }
+        let next;
+        try {
+            next = decodeURIComponent(decoded);
+        }
+        catch {
+            return false;
+        }
+        if (next === decoded) {
+            return true;
+        }
+        decoded = next;
+    }
+    return false;
+}
+exports.RelayPodReturnPathSchema = zod_1.z
+    .string()
+    .min(1)
+    .refine(isSafeRelayReturnPath, {
+    message: 'Return path must be a safe pod-local path',
+});
+exports.AuthorizeRelayPodBodySchema = zod_1.z
+    .object({
+    returnPath: exports.RelayPodReturnPathSchema,
+    outreachRequestId: zod_1.z.string().uuid().optional(),
+})
+    .strict();
+exports.AuthorizeRelayPodResponseSchema = zod_1.z
+    .object({
+    redirectUrl: zod_1.z.string().url(),
+})
+    .strict();
+const idPathParams = zod_1.z.object({ id: zod_1.z.string().uuid() }).strict();
+exports.relayPodsContract = c.router({
+    mine: {
+        method: 'GET',
+        path: '/relay-pods/mine',
+        responses: { 200: zod_1.z.array(relay_pods_schemas_1.RelayPodSchema) },
+        summary: 'List Relay pods manageable by the current user',
+        metadata: { tags: ['Relay Pods'] },
+    },
+    list: {
+        method: 'GET',
+        path: '/relay-pods',
+        responses: { 200: zod_1.z.array(relay_pods_schemas_1.RelayPodSchema) },
+        summary: 'List Relay pods',
+        metadata: { tags: ['Relay Pods'] },
+    },
+    create: {
+        method: 'POST',
+        path: '/relay-pods',
+        body: exports.CreateRelayPodBodySchema,
+        responses: {
+            201: relay_pods_schemas_1.RelayPodSchema,
+            409: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Create a Relay pod',
+        metadata: { tags: ['Relay Pods'] },
+    },
+    update: {
+        method: 'PATCH',
+        path: '/relay-pods/:id',
+        pathParams: idPathParams,
+        body: exports.UpdateRelayPodBodySchema,
+        responses: {
+            200: relay_pods_schemas_1.RelayPodSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+            409: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Update a Relay pod',
+        metadata: { tags: ['Relay Pods'] },
+    },
+    createCredential: {
+        method: 'POST',
+        path: '/relay-pods/:id/credentials',
+        pathParams: idPathParams,
+        body: exports.CreateRelayPodCredentialBodySchema,
+        responses: {
+            201: relay_pods_schemas_1.RelayPodCredentialCreatedSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Create a Relay pod credential',
+        metadata: { tags: ['Relay Pods'] },
+    },
+    revokeCredential: {
+        method: 'POST',
+        path: '/relay-pods/:id/credentials/:credentialId/revoke',
+        pathParams: zod_1.z
+            .object({
+            id: zod_1.z.string().uuid(),
+            credentialId: zod_1.z.string().uuid(),
+        })
+            .strict(),
+        body: zod_1.z.object({}).strict(),
+        responses: {
+            200: relay_pods_schemas_1.RelayPodCredentialMetadataSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Revoke a Relay pod credential',
+        metadata: { tags: ['Relay Pods'] },
+    },
+    authorize: {
+        method: 'POST',
+        path: '/relay-pods/:id/authorize',
+        pathParams: idPathParams,
+        body: exports.AuthorizeRelayPodBodySchema,
+        responses: {
+            200: exports.AuthorizeRelayPodResponseSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Authorize a human session on a Relay pod',
+        metadata: { tags: ['Relay Pods'] },
+    },
+    me: {
+        method: 'GET',
+        path: '/relay-pods/me',
+        responses: { 200: relay_pods_schemas_1.RelayPodSummarySchema },
+        summary: 'Read the authenticated Relay pod identity',
+        metadata: { tags: ['Relay Pods'] },
+    },
+}, {
+    pathPrefix: '/v2',
+    commonResponses: {
+        400: error_schemas_1.ErrorResponseSchema,
+        401: error_schemas_1.ErrorResponseSchema,
+        403: error_schemas_1.ErrorResponseSchema,
+        500: error_schemas_1.ErrorResponseSchema,
+    },
+});

package/dist/relay-pods/relay-pods.contract.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=relay-pods.contract.spec.d.ts.map

package/dist/relay-pods/relay-pods.contract.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-pods.contract.spec.d.ts","sourceRoot":"","sources":["../../contracts/relay-pods/relay-pods.contract.spec.ts"],"names":[],"mappings":""}

package/dist/relay-pods/relay-pods.contract.spec.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const bun_test_1 = require("bun:test");
+const index_1 = require("../index");
+const relay_pods_contract_1 = require("./relay-pods.contract");
+const ownerId = '11111111-1111-4111-8111-111111111111';
+const podId = '22222222-2222-4222-8222-222222222222';
+const credentialId = '33333333-3333-4333-8333-333333333333';
+const now = '2026-08-01T09:00:00.000Z';
+const metadata = {
+    id: credentialId,
+    tokenIdentifier: 'pod_01',
+    createdAt: now,
+    expiresAt: null,
+    revokedAt: null,
+    lastUsedAt: null,
+};
+const activePod = {
+    id: podId,
+    slug: 'pod-01',
+    displayName: 'Pod 01',
+    ownerUserId: ownerId,
+    ownerName: 'Relay Owner',
+    publicBaseUrl: 'https://pod.test',
+    status: 'ACTIVE',
+    credentials: [metadata],
+    createdAt: now,
+    updatedAt: now,
+};
+(0, bun_test_1.describe)('relay pod schemas', () => {
+    (0, bun_test_1.it)('publishes the owner-scoped pod shape and requires HTTPS', () => {
+        (0, bun_test_1.expect)(relay_pods_contract_1.RelayPodSchema.parse(activePod).ownerUserId).toBe(ownerId);
+        (0, bun_test_1.expect)(() => relay_pods_contract_1.RelayPodSchema.parse({
+            ...activePod,
+            publicBaseUrl: 'http://pod.test',
+        })).toThrow();
+    });
+    (0, bun_test_1.it)('returns a raw credential token only from credential creation', () => {
+        const rawToken = 'pod_01.super-secret-token';
+        (0, bun_test_1.expect)(relay_pods_contract_1.RelayPodCredentialCreatedSchema.parse({
+            credential: metadata,
+            token: rawToken,
+        }).token).toBe(rawToken);
+        (0, bun_test_1.expect)(relay_pods_contract_1.RelayPodCredentialMetadataSchema.safeParse({
+            ...metadata,
+            token: rawToken,
+        }).success).toBe(false);
+    });
+    (0, bun_test_1.it)('keeps slug creation-only and supports explicit forced updates', () => {
+        (0, bun_test_1.expect)(relay_pods_contract_1.CreateRelayPodBodySchema.parse({
+            slug: activePod.slug,
+            displayName: activePod.displayName,
+            ownerUserId: activePod.ownerUserId,
+            publicBaseUrl: activePod.publicBaseUrl,
+        }).status).toBeUndefined();
+        (0, bun_test_1.expect)(relay_pods_contract_1.UpdateRelayPodBodySchema.parse({ status: 'INACTIVE', force: true })).toEqual({ status: 'INACTIVE', force: true });
+        (0, bun_test_1.expect)(relay_pods_contract_1.UpdateRelayPodBodySchema.safeParse({ slug: 'renamed-pod' }).success).toBe(false);
+    });
+    (0, bun_test_1.it)('allows a credential expiry without accepting credential material', () => {
+        (0, bun_test_1.expect)(relay_pods_contract_1.CreateRelayPodCredentialBodySchema.parse({ expiresAt: null }).expiresAt).toBeNull();
+        (0, bun_test_1.expect)(relay_pods_contract_1.CreateRelayPodCredentialBodySchema.safeParse({ token: 'caller-token' })
+            .success).toBe(false);
+    });
+    (0, bun_test_1.it)('keeps authorization input pod-local and returns only a redirect URL', () => {
+        (0, bun_test_1.expect)(relay_pods_contract_1.AuthorizeRelayPodBodySchema.parse({ returnPath: '/outreach/requests/42' })
+            .returnPath).toStartWith('/');
+        (0, bun_test_1.expect)(relay_pods_contract_1.AuthorizeRelayPodBodySchema.parse({
+            returnPath: '/outreach%252Frequests%252F42',
+        }).returnPath).toBe('/outreach%252Frequests%252F42');
+        (0, bun_test_1.expect)(relay_pods_contract_1.AuthorizeRelayPodBodySchema.safeParse({
+            returnPath: 'https://other.example/path',
+        }).success).toBe(false);
+        for (const returnPath of [
+            '//other.example/path',
+            '/\\other.example/path',
+            '/%2F%2Fother.example/path',
+            '/%5Cother.example/path',
+            '/%252525255c',
+            '/%252525252f%252525252fevil.example',
+        ]) {
+            (0, bun_test_1.expect)(relay_pods_contract_1.AuthorizeRelayPodBodySchema.safeParse({ returnPath }).success).toBe(false);
+        }
+        (0, bun_test_1.expect)(relay_pods_contract_1.AuthorizeRelayPodResponseSchema.safeParse({
+            redirectUrl: 'https://pod.test/auth/callback?code=opaque',
+            codeHash: 'must-not-leak',
+        }).success).toBe(false);
+    });
+});
+(0, bun_test_1.describe)('relayPodsContract routes', () => {
+    (0, bun_test_1.it)('publishes every human/admin route and the machine identity route', () => {
+        (0, bun_test_1.expect)(relay_pods_contract_1.relayPodsContract.mine).toMatchObject({
+            method: 'GET',
+            path: '/v2/relay-pods/mine',
+        });
+        (0, bun_test_1.expect)(relay_pods_contract_1.relayPodsContract.list).toMatchObject({
+            method: 'GET',
+            path: '/v2/relay-pods',
+        });
+        (0, bun_test_1.expect)(relay_pods_contract_1.relayPodsContract.create).toMatchObject({
+            method: 'POST',
+            path: '/v2/relay-pods',
+        });
+        (0, bun_test_1.expect)(relay_pods_contract_1.relayPodsContract.update).toMatchObject({
+            method: 'PATCH',
+            path: '/v2/relay-pods/:id',
+        });
+        (0, bun_test_1.expect)(relay_pods_contract_1.relayPodsContract.createCredential).toMatchObject({
+            method: 'POST',
+            path: '/v2/relay-pods/:id/credentials',
+        });
+        (0, bun_test_1.expect)(relay_pods_contract_1.relayPodsContract.revokeCredential).toMatchObject({
+            method: 'POST',
+            path: '/v2/relay-pods/:id/credentials/:credentialId/revoke',
+        });
+        (0, bun_test_1.expect)(relay_pods_contract_1.relayPodsContract.authorize).toMatchObject({
+            method: 'POST',
+            path: '/v2/relay-pods/:id/authorize',
+        });
+        (0, bun_test_1.expect)(relay_pods_contract_1.relayPodsContract.me).toMatchObject({
+            method: 'GET',
+            path: '/v2/relay-pods/me',
+        });
+        (0, bun_test_1.expect)(relay_pods_contract_1.relayPodsContract.create.responses).toHaveProperty('201');
+        (0, bun_test_1.expect)(relay_pods_contract_1.relayPodsContract.createCredential.responses).toHaveProperty('201');
+        (0, bun_test_1.expect)(index_1.apiContractRouter.RelayPods.me.path).toBe('/v2/relay-pods/me');
+    });
+    (0, bun_test_1.it)('does not expose persisted secret fields from pod responses', () => {
+        (0, bun_test_1.expect)(relay_pods_contract_1.relayPodsContract.list.responses[200].safeParse([
+            {
+                ...activePod,
+                credentials: [
+                    {
+                        ...metadata,
+                        secretHash: 'must-not-leak',
+                        token: 'must-not-leak',
+                    },
+                ],
+            },
+        ]).success).toBe(false);
+    });
+});