crossly.client.auth.service 0.0.1

package/dist/repository/inMemoryClientRepository.js

@@ -0,0 +1,60 @@
+/**
+ * In-memory implementation of {@link IClientRepository}.
+ *
+ * State lives in two Maps (by clientId, and a (provider, subject) -> clientId
+ * index) and is lost on restart. Used by the unit tests and for running locally
+ * without a database; {@link PgClientRepository} is the durable implementation
+ * wired into the service at runtime. Records are cloned on the way in and out so
+ * callers cannot mutate stored state by reference.
+ */
+export class InMemoryClientRepository {
+    constructor() {
+        this.byClientId = new Map();
+        this.byIdentity = new Map();
+    }
+    async findByProvider(provider, providerSubject) {
+        const clientId = this.byIdentity.get(this.identityKey(provider, providerSubject));
+        if (!clientId) {
+            return undefined;
+        }
+        const found = this.byClientId.get(clientId);
+        return found ? { ...found } : undefined;
+    }
+    async findById(clientId) {
+        const found = this.byClientId.get(clientId);
+        return found ? { ...found } : undefined;
+    }
+    async create(client) {
+        const idKey = this.identityKey(client.provider, client.providerSubject);
+        if (this.byClientId.has(client.clientId)) {
+            throw new Error(`client already exists: ${client.clientId}`);
+        }
+        if (this.byIdentity.has(idKey)) {
+            throw new Error(`identity already mapped: ${client.provider}/${client.providerSubject}`);
+        }
+        const record = {
+            clientId: client.clientId,
+            provider: client.provider,
+            providerSubject: client.providerSubject,
+            email: client.email,
+            createdAt: new Date(),
+            lastLoginAt: undefined,
+        };
+        this.byClientId.set(record.clientId, record);
+        this.byIdentity.set(idKey, record.clientId);
+        return { ...record };
+    }
+    async touchLastLogin(clientId) {
+        const existing = this.byClientId.get(clientId);
+        if (!existing) {
+            return;
+        }
+        existing.lastLoginAt = new Date();
+    }
+    // A unique key for a (provider, subject) pair. The pair is JSON-encoded so no
+    // combination of provider/subject characters can produce a colliding key.
+    identityKey(provider, providerSubject) {
+        return JSON.stringify([provider, providerSubject]);
+    }
+}
+//# sourceMappingURL=inMemoryClientRepository.js.map

package/dist/repository/inMemoryClientRepository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inMemoryClientRepository.js","sourceRoot":"","sources":["../../src/repository/inMemoryClientRepository.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,OAAO,wBAAwB;IAArC;QACqB,eAAU,GAA8B,IAAI,GAAG,EAAE,CAAC;QAClD,eAAU,GAAwB,IAAI,GAAG,EAAE,CAAC;IA0DjE,CAAC;IAxDU,KAAK,CAAC,cAAc,CACvB,QAAgB,EAChB,eAAuB;QAEvB,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC;QAClF,IAAI,CAAC,QAAQ,EAAE,CAAC;YACZ,OAAO,SAAS,CAAC;QACrB,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC5C,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5C,CAAC;IAEM,KAAK,CAAC,QAAQ,CAAC,QAAgB;QAClC,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC5C,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5C,CAAC;IAEM,KAAK,CAAC,MAAM,CAAC,MAAiB;QACjC,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,eAAe,CAAC,CAAC;QAExE,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CAAC,0BAA0B,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,4BAA4B,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC,CAAC;QAC7F,CAAC;QAED,MAAM,MAAM,GAAiB;YACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,eAAe,EAAE,MAAM,CAAC,eAAe;YACvC,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,SAAS,EAAE,IAAI,IAAI,EAAE;YACrB,WAAW,EAAE,SAAS;SACzB,CAAC;QAEF,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC7C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC5C,OAAO,EAAE,GAAG,MAAM,EAAE,CAAC;IACzB,CAAC;IAEM,KAAK,CAAC,cAAc,CAAC,QAAgB;QACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC/C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACZ,OAAO;QACX,CAAC;QAED,QAAQ,CAAC,WAAW,GAAG,IAAI,IAAI,EAAE,CAAC;IACtC,CAAC;IAED,8EAA8E;IAC9E,0EAA0E;IAClE,WAAW,CAAC,QAAgB,EAAE,eAAuB;QACzD,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC;IACvD,CAAC;CACJ","sourcesContent":["import type { ClientRecord, IClientRepository, NewClient } from './types.js';\n\n/**\n * In-memory implementation of {@link IClientRepository}.\n *\n * State lives in two Maps (by clientId, and a (provider, subject) -> clientId\n * index) and is lost on restart. Used by the unit tests and for running locally\n * without a database; {@link PgClientRepository} is the durable implementation\n * wired into the service at runtime. Records are cloned on the way in and out so\n * callers cannot mutate stored state by reference.\n */\nexport class InMemoryClientRepository implements IClientRepository {\n    private readonly byClientId: Map<string, ClientRecord> = new Map();\n    private readonly byIdentity: Map<string, string> = new Map();\n\n    public async findByProvider(\n        provider: string,\n        providerSubject: string,\n    ): Promise<ClientRecord | undefined> {\n        const clientId = this.byIdentity.get(this.identityKey(provider, providerSubject));\n        if (!clientId) {\n            return undefined;\n        }\n\n        const found = this.byClientId.get(clientId);\n        return found ? { ...found } : undefined;\n    }\n\n    public async findById(clientId: string): Promise<ClientRecord | undefined> {\n        const found = this.byClientId.get(clientId);\n        return found ? { ...found } : undefined;\n    }\n\n    public async create(client: NewClient): Promise<ClientRecord> {\n        const idKey = this.identityKey(client.provider, client.providerSubject);\n\n        if (this.byClientId.has(client.clientId)) {\n            throw new Error(`client already exists: ${client.clientId}`);\n        }\n        if (this.byIdentity.has(idKey)) {\n            throw new Error(`identity already mapped: ${client.provider}/${client.providerSubject}`);\n        }\n\n        const record: ClientRecord = {\n            clientId: client.clientId,\n            provider: client.provider,\n            providerSubject: client.providerSubject,\n            email: client.email,\n            createdAt: new Date(),\n            lastLoginAt: undefined,\n        };\n\n        this.byClientId.set(record.clientId, record);\n        this.byIdentity.set(idKey, record.clientId);\n        return { ...record };\n    }\n\n    public async touchLastLogin(clientId: string): Promise<void> {\n        const existing = this.byClientId.get(clientId);\n        if (!existing) {\n            return;\n        }\n\n        existing.lastLoginAt = new Date();\n    }\n\n    // A unique key for a (provider, subject) pair. The pair is JSON-encoded so no\n    // combination of provider/subject characters can produce a colliding key.\n    private identityKey(provider: string, providerSubject: string): string {\n        return JSON.stringify([provider, providerSubject]);\n    }\n}\n"]}

package/dist/repository/pgClientRepository.js

@@ -0,0 +1,45 @@
+/**
+ * PostgreSQL-backed implementation of {@link IClientRepository}.
+ *
+ * A connected {@link pg.Pool} is injected; its lifecycle (and the schema, via the
+ * migration runner) is owned by the composition root. The UNIQUE (provider,
+ * provider_subject) constraint enforces one client per external identity at the
+ * database level, so a concurrent duplicate `create` rejects rather than racing.
+ */
+export class PgClientRepository {
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async findByProvider(provider, providerSubject) {
+        const result = await this.pool.query('SELECT * FROM clients WHERE provider = $1 AND provider_subject = $2', [provider, providerSubject]);
+        const row = result.rows[0];
+        return row ? this.toDomain(row) : undefined;
+    }
+    async findById(clientId) {
+        const result = await this.pool.query('SELECT * FROM clients WHERE client_id = $1', [clientId]);
+        const row = result.rows[0];
+        return row ? this.toDomain(row) : undefined;
+    }
+    async create(client) {
+        const result = await this.pool.query(`INSERT INTO clients (client_id, provider, provider_subject, email)
+             VALUES ($1, $2, $3, $4)
+             RETURNING *`, [client.clientId, client.provider, client.providerSubject, client.email ?? null]);
+        return this.toDomain(result.rows[0]);
+    }
+    async touchLastLogin(clientId) {
+        await this.pool.query('UPDATE clients SET last_login_at = now() WHERE client_id = $1', [
+            clientId,
+        ]);
+    }
+    toDomain(row) {
+        return {
+            clientId: row.client_id,
+            provider: row.provider,
+            providerSubject: row.provider_subject,
+            email: row.email ?? undefined,
+            createdAt: row.created_at,
+            lastLoginAt: row.last_login_at ?? undefined,
+        };
+    }
+}
+//# sourceMappingURL=pgClientRepository.js.map

package/dist/repository/pgClientRepository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pgClientRepository.js","sourceRoot":"","sources":["../../src/repository/pgClientRepository.ts"],"names":[],"mappings":"AAaA;;;;;;;GAOG;AACH,MAAM,OAAO,kBAAkB;IAC3B,YAAoC,IAAa;QAAb,SAAI,GAAJ,IAAI,CAAS;IAAG,CAAC;IAE9C,KAAK,CAAC,cAAc,CACvB,QAAgB,EAChB,eAAuB;QAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAChC,qEAAqE,EACrE,CAAC,QAAQ,EAAE,eAAe,CAAC,CAC9B,CAAC;QAEF,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC3B,OAAO,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAChD,CAAC;IAEM,KAAK,CAAC,QAAQ,CAAC,QAAgB;QAClC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAChC,4CAA4C,EAC5C,CAAC,QAAQ,CAAC,CACb,CAAC;QAEF,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC3B,OAAO,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAChD,CAAC;IAEM,KAAK,CAAC,MAAM,CAAC,MAAiB;QACjC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAChC;;yBAEa,EACb,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,KAAK,IAAI,IAAI,CAAC,CACnF,CAAC;QAEF,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC;IAEM,KAAK,CAAC,cAAc,CAAC,QAAgB;QACxC,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,+DAA+D,EAAE;YACnF,QAAQ;SACX,CAAC,CAAC;IACP,CAAC;IAEO,QAAQ,CAAC,GAAc;QAC3B,OAAO;YACH,QAAQ,EAAE,GAAG,CAAC,SAAS;YACvB,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,eAAe,EAAE,GAAG,CAAC,gBAAgB;YACrC,KAAK,EAAE,GAAG,CAAC,KAAK,IAAI,SAAS;YAC7B,SAAS,EAAE,GAAG,CAAC,UAAU;YACzB,WAAW,EAAE,GAAG,CAAC,aAAa,IAAI,SAAS;SAC9C,CAAC;IACN,CAAC;CACJ","sourcesContent":["import pg from 'pg';\nimport type { ClientRecord, IClientRepository, NewClient } from './types.js';\n\n/** Raw row shape returned from the `clients` table. */\ninterface ClientRow {\n    client_id: string;\n    provider: string;\n    provider_subject: string;\n    email: string | null;\n    created_at: Date;\n    last_login_at: Date | null;\n}\n\n/**\n * PostgreSQL-backed implementation of {@link IClientRepository}.\n *\n * A connected {@link pg.Pool} is injected; its lifecycle (and the schema, via the\n * migration runner) is owned by the composition root. The UNIQUE (provider,\n * provider_subject) constraint enforces one client per external identity at the\n * database level, so a concurrent duplicate `create` rejects rather than racing.\n */\nexport class PgClientRepository implements IClientRepository {\n    public constructor(private readonly pool: pg.Pool) {}\n\n    public async findByProvider(\n        provider: string,\n        providerSubject: string,\n    ): Promise<ClientRecord | undefined> {\n        const result = await this.pool.query<ClientRow>(\n            'SELECT * FROM clients WHERE provider = $1 AND provider_subject = $2',\n            [provider, providerSubject],\n        );\n\n        const row = result.rows[0];\n        return row ? this.toDomain(row) : undefined;\n    }\n\n    public async findById(clientId: string): Promise<ClientRecord | undefined> {\n        const result = await this.pool.query<ClientRow>(\n            'SELECT * FROM clients WHERE client_id = $1',\n            [clientId],\n        );\n\n        const row = result.rows[0];\n        return row ? this.toDomain(row) : undefined;\n    }\n\n    public async create(client: NewClient): Promise<ClientRecord> {\n        const result = await this.pool.query<ClientRow>(\n            `INSERT INTO clients (client_id, provider, provider_subject, email)\n             VALUES ($1, $2, $3, $4)\n             RETURNING *`,\n            [client.clientId, client.provider, client.providerSubject, client.email ?? null],\n        );\n\n        return this.toDomain(result.rows[0]);\n    }\n\n    public async touchLastLogin(clientId: string): Promise<void> {\n        await this.pool.query('UPDATE clients SET last_login_at = now() WHERE client_id = $1', [\n            clientId,\n        ]);\n    }\n\n    private toDomain(row: ClientRow): ClientRecord {\n        return {\n            clientId: row.client_id,\n            provider: row.provider,\n            providerSubject: row.provider_subject,\n            email: row.email ?? undefined,\n            createdAt: row.created_at,\n            lastLoginAt: row.last_login_at ?? undefined,\n        };\n    }\n}\n"]}

package/dist/repository/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/repository/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/repository/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * A persisted client (account).\n *\n * `clientId` equals the token `sub` and is immutable for the life of the client\n * (it is reused from the guest's id on promote-in-place). Identity is the pair\n * `(provider, providerSubject)` — the provider's stable subject is matched\n * directly; email is stored for display/contact only and is NEVER a matching key.\n *\n * Guests are NOT stored here — only clients that have logged in at least once.\n */\nexport interface ClientRecord {\n    clientId: string;\n    provider: string;\n    providerSubject: string;\n    email?: string;\n    createdAt: Date;\n    lastLoginAt?: Date;\n}\n\n/** Fields required to insert a new client. */\nexport interface NewClient {\n    clientId: string;\n    provider: string;\n    providerSubject: string;\n    email?: string;\n}\n\n/**\n * Persistence boundary for authenticated clients (accounts).\n *\n * Implementations may be Postgres ({@link PgClientRepository}) or in-memory\n * ({@link InMemoryClientRepository}); the rest of the service depends only on\n * this interface.\n */\nexport interface IClientRepository {\n    /** Find a client by its external identity. Returns undefined if none exists. */\n    findByProvider(provider: string, providerSubject: string): Promise<ClientRecord | undefined>;\n\n    /** Find a client by its immutable clientId. Returns undefined if none exists. */\n    findById(clientId: string): Promise<ClientRecord | undefined>;\n\n    /**\n     * Insert a new client. Rejects if `clientId` already exists or if\n     * `(provider, providerSubject)` is already mapped to another client.\n     */\n    create(client: NewClient): Promise<ClientRecord>;\n\n    /** Set last_login_at to now for the given client. No-op if the client is unknown. */\n    touchLastLogin(clientId: string): Promise<void>;\n}\n"]}

package/dist/signer/jwtSigner.js

@@ -0,0 +1,36 @@
+import { SignJWT, jwtVerify } from 'jose';
+/**
+ * HS256 JWT signer backed by `jose`.
+ *
+ * "Extremely simple" by design: a single shared secret both signs and verifies
+ * tokens. When real identity providers are introduced, swap this for an
+ * RS256/JWKS implementation of {@link IJwtSigner} — nothing else in the service
+ * (or in consumers) changes, because the token shape stays the same.
+ */
+export class JwtSigner {
+    constructor(secret) {
+        this.key = new TextEncoder().encode(secret);
+    }
+    async sign(sub, guest, ttlSeconds) {
+        const issuedAt = Math.floor(Date.now() / 1000);
+        const expiresAt = issuedAt + ttlSeconds;
+        const token = await new SignJWT({ guest })
+            .setProtectedHeader({ alg: JwtSigner.algorithm })
+            .setSubject(sub)
+            .setIssuedAt(issuedAt)
+            .setExpirationTime(expiresAt)
+            .sign(this.key);
+        return { token, expiresAt };
+    }
+    async verify(token) {
+        const { payload } = await jwtVerify(token, this.key);
+        return {
+            sub: payload.sub,
+            guest: payload.guest,
+            iat: payload.iat,
+            exp: payload.exp,
+        };
+    }
+}
+JwtSigner.algorithm = 'HS256';
+//# sourceMappingURL=jwtSigner.js.map

package/dist/signer/jwtSigner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwtSigner.js","sourceRoot":"","sources":["../../src/signer/jwtSigner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAI1C;;;;;;;GAOG;AACH,MAAM,OAAO,SAAS;IAIlB,YAAmB,MAAc;QAC7B,IAAI,CAAC,GAAG,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAChD,CAAC;IAEM,KAAK,CAAC,IAAI,CACb,GAAW,EACX,KAAc,EACd,UAAkB;QAElB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAC/C,MAAM,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC;QAExC,MAAM,KAAK,GAAG,MAAM,IAAI,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC;aACrC,kBAAkB,CAAC,EAAE,GAAG,EAAE,SAAS,CAAC,SAAS,EAAE,CAAC;aAChD,UAAU,CAAC,GAAG,CAAC;aACf,WAAW,CAAC,QAAQ,CAAC;aACrB,iBAAiB,CAAC,SAAS,CAAC;aAC5B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAEpB,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAChC,CAAC;IAEM,KAAK,CAAC,MAAM,CAAC,KAAa;QAC7B,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QAErD,OAAO;YACH,GAAG,EAAE,OAAO,CAAC,GAAa;YAC1B,KAAK,EAAE,OAAO,CAAC,KAAgB;YAC/B,GAAG,EAAE,OAAO,CAAC,GAAa;YAC1B,GAAG,EAAE,OAAO,CAAC,GAAa;SAC7B,CAAC;IACN,CAAC;;AAlCuB,mBAAS,GAAW,OAAO,CAAC","sourcesContent":["import { SignJWT, jwtVerify } from 'jose';\nimport type { AccessTokenClaims } from '@textyly/crossly-client-auth-contracts';\nimport type { IJwtSigner } from './types.js';\n\n/**\n * HS256 JWT signer backed by `jose`.\n *\n * \"Extremely simple\" by design: a single shared secret both signs and verifies\n * tokens. When real identity providers are introduced, swap this for an\n * RS256/JWKS implementation of {@link IJwtSigner} — nothing else in the service\n * (or in consumers) changes, because the token shape stays the same.\n */\nexport class JwtSigner implements IJwtSigner {\n    private static readonly algorithm: string = 'HS256';\n    private readonly key: Uint8Array;\n\n    public constructor(secret: string) {\n        this.key = new TextEncoder().encode(secret);\n    }\n\n    public async sign(\n        sub: string,\n        guest: boolean,\n        ttlSeconds: number,\n    ): Promise<{ token: string; expiresAt: number }> {\n        const issuedAt = Math.floor(Date.now() / 1000);\n        const expiresAt = issuedAt + ttlSeconds;\n\n        const token = await new SignJWT({ guest })\n            .setProtectedHeader({ alg: JwtSigner.algorithm })\n            .setSubject(sub)\n            .setIssuedAt(issuedAt)\n            .setExpirationTime(expiresAt)\n            .sign(this.key);\n\n        return { token, expiresAt };\n    }\n\n    public async verify(token: string): Promise<AccessTokenClaims> {\n        const { payload } = await jwtVerify(token, this.key);\n\n        return {\n            sub: payload.sub as string,\n            guest: payload.guest as boolean,\n            iat: payload.iat as number,\n            exp: payload.exp as number,\n        };\n    }\n}\n"]}

package/dist/signer/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/signer/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/signer/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { AccessTokenClaims } from '@textyly/crossly-client-auth-contracts';\n\n/**\n * Token signing/verification boundary — the lowest layer of the service\n * (the auth analogue of a repository). Implementations wrap a concrete JWT\n * library + key; the rest of the service depends only on this interface.\n */\nexport interface IJwtSigner {\n    /** Sign an access token for `sub`, valid for `ttlSeconds`. Returns the token and its expiry. */\n    sign(sub: string, guest: boolean, ttlSeconds: number): Promise<{ token: string; expiresAt: number }>;\n\n    /** Verify a token and return its claims, or throw if it is invalid or expired. */\n    verify(token: string): Promise<AccessTokenClaims>;\n}\n"]}

package/docker-compose.yml

@@ -0,0 +1,25 @@
+# Local dev Postgres for crossly.client.auth.service.
+#
+#   docker compose up -d      # start
+#   docker compose down       # stop (keeps data)
+#   docker compose down -v     # stop and wipe data
+#
+# Published on host port 5433 (not 5432) so it can coexist with a native Postgres
+# that already owns 5432. Matches the default DATABASE_URL used by the migration
+# runner and the service:
+#   postgres://crossly:crossly@127.0.0.1:5433/crossly_auth
+services:
+  postgres:
+    image: postgres:17
+    container_name: crossly-auth-postgres
+    environment:
+      POSTGRES_USER: crossly
+      POSTGRES_PASSWORD: crossly
+      POSTGRES_DB: crossly_auth
+    ports:
+      - "5433:5432"
+    volumes:
+      - crossly-auth-pgdata:/var/lib/postgresql/data
+
+volumes:
+  crossly-auth-pgdata:

package/migrations/0001_create_clients.sql

@@ -0,0 +1,16 @@
+-- Clients (authenticated accounts) for crossly.client.auth.service.
+--
+-- client_id == the token `sub`; immutable, reused from the guest's id on
+-- promote-in-place. Identity is the (provider, provider_subject) pair — the
+-- provider's stable subject. email is for display/contact only, NEVER a
+-- matching key. Guests are not stored here — only clients that have logged in.
+
+CREATE TABLE IF NOT EXISTS clients (
+    client_id        UUID PRIMARY KEY,
+    provider         TEXT NOT NULL,
+    provider_subject TEXT NOT NULL,
+    email            TEXT,
+    created_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
+    last_login_at    TIMESTAMPTZ,
+    UNIQUE (provider, provider_subject)
+);

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "crossly.client.auth.service",
+  "version": "0.0.1",
+  "description": "TBD",
+  "main": "dist/app.js",
+  "type": "module",
+  "scripts": {
+    "compile": "tsc --version && tsc -p tsconfig.build.json",
+    "build:contracts": "tsc -p contracts/tsconfig.json",
+    "build": "npm i && npm run build:contracts && npm run compile",
+    "start": "npm run build && node dist/app.js",
+    "db:up": "docker compose up -d",
+    "db:down": "docker compose down",
+    "migrate": "npm run compile && node dist/db/migrate.js",
+    "compile:tests": "tsc --version && tsc -p tsconfig.test.json",
+    "build:tests": "npm run build && npm run compile:tests",
+    "test": "npm run build:tests && mocha 'dist-tests/tests/**/*.test.js'",
+    "test:unit": "npm run build:tests && mocha 'dist-tests/tests/unit/**/*.test.js'",
+    "test:integration": "npm run build:tests && mocha 'dist-tests/tests/integration/**/*.test.js'"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/textyly/crossly.client.auth.service.git"
+  },
+  "author": "textyly community",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@types/cors": "^2.8.19",
+    "cookie-parser": "^1.4.7",
+    "cors": "^2.8.6",
+    "dotenv": "^17.4.2",
+    "express": "^4.19.2",
+    "jose": "^5.9.6",
+    "openid-client": "^6.8.4",
+    "pg": "^8.13.1"
+  },
+  "devDependencies": {
+    "@types/chai": "^5.0.0",
+    "@types/cookie-parser": "^1.4.10",
+    "@types/express": "^4.17.21",
+    "@types/mocha": "^10.0.8",
+    "@types/node": "^20.0.0",
+    "@types/pg": "^8.11.10",
+    "@types/supertest": "^7.2.0",
+    "chai": "^5.1.1",
+    "mocha": "^10.7.3",
+    "supertest": "^7.2.2",
+    "typescript": "^5.6.2"
+  }
+}

package/src/app.ts

@@ -0,0 +1,61 @@
+import 'dotenv/config';
+import pg from 'pg';
+import { createApp } from './createApp.js';
+import { JwtSigner } from './signer/jwtSigner.js';
+import { PgClientRepository } from './repository/pgClientRepository.js';
+import { databaseUrl, runMigrations } from './db/migrate.js';
+import { loadConfig, loadGoogleConfig } from './config.js';
+import { GoogleProvider } from './oidc/googleProvider.js';
+import { NotConfiguredOidcProvider } from './oidc/notConfiguredOidcProvider.js';
+import type { IOidcProvider } from './oidc/types.js';
+
+const port = 5001;
+// HS256 shared secret. MUST be overridden via AUTH_JWT_SECRET in any real environment.
+const secret = process.env.AUTH_JWT_SECRET ?? 'dev-only-insecure-secret-change-me';
+
+/** Build the real Google provider if configured, else a disabled placeholder. */
+async function buildOidcProvider(): Promise<IOidcProvider> {
+    const google = loadGoogleConfig();
+    if (google.clientId && google.clientSecret) {
+        return GoogleProvider.create({
+            clientId: google.clientId,
+            clientSecret: google.clientSecret,
+            redirectUri: google.callbackUrl,
+        });
+    }
+
+    console.warn(
+        'Google OIDC not configured (set GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET) — /auth/login is disabled',
+    );
+    return new NotConfiguredOidcProvider();
+}
+
+/**
+ * Entry point: apply database migrations, then build the app via the shared
+ * factory and listen.
+ *
+ * Migrations run on startup and are safe across several instances booting in
+ * parallel (an advisory lock serializes them — see db/migrate.ts), so no separate
+ * migration job is required. The service will not start serving until the schema
+ * is up to date, which means a reachable Postgres is now required to boot.
+ */
+async function main(): Promise<void> {
+    await runMigrations();
+
+    // One pool for the app's lifetime, backing the client repository.
+    const pool = new pg.Pool({ connectionString: databaseUrl() });
+    const signer = new JwtSigner(secret);
+    const clients = new PgClientRepository(pool);
+    const oidc = await buildOidcProvider();
+    const config = loadConfig();
+    const app = createApp({ signer, clients, oidc, config });
+
+    app.listen(port, () => {
+        console.log(`crossly.client.auth.service listening on port ${port}`);
+    });
+}
+
+main().catch((error) => {
+    console.error('failed to start crossly.client.auth.service:', error);
+    process.exit(1);
+});

package/src/config.ts

@@ -0,0 +1,51 @@
+/**
+ * Service configuration, read from the environment with dev-friendly defaults.
+ * Secrets/URLs come from env (k8s Secret/ConfigMap later); the defaults make
+ * local dev work with zero setup (except Google login, which needs real creds).
+ */
+
+/** httpOnly cookie holding the session JWT (guest or authenticated). */
+export const SESSION_COOKIE = 'crossly_session';
+
+/** Short-lived signed cookie holding the OAuth `state` + PKCE `codeVerifier`. */
+export const OAUTH_COOKIE = 'crossly_oauth';
+
+/** Runtime config for cookies, CORS and post-login redirects. */
+export interface AuthConfig {
+    /** Secret used to sign the short-lived OAuth cookie. */
+    cookieSecret: string;
+    /** Where the browser is sent after a successful login / after logout. */
+    uiRedirectUrl: string;
+    /** Allowed browser origin for credentialed CORS requests. */
+    corsOrigin: string;
+    /** Whether cookies carry the `Secure` attribute (true behind HTTPS). */
+    secureCookies: boolean;
+}
+
+/** Google OAuth client config; clientId/secret absent ⇒ login is disabled. */
+export interface GoogleConfig {
+    clientId?: string;
+    clientSecret?: string;
+    callbackUrl: string;
+}
+
+export function loadConfig(): AuthConfig {
+    // Where the browser lands after login. May include a path (e.g. the static
+    // UI entry); the CORS origin is derived from just its scheme+host+port, since
+    // the browser's Origin header never carries a path.
+    const uiRedirectUrl = process.env.UI_URL ?? 'http://localhost:5000/dist/index.html';
+    return {
+        cookieSecret: process.env.COOKIE_SECRET ?? 'dev-only-cookie-secret-change-me',
+        uiRedirectUrl,
+        corsOrigin: process.env.CORS_ORIGIN ?? new URL(uiRedirectUrl).origin,
+        secureCookies: (process.env.SECURE_COOKIES ?? 'false') === 'true',
+    };
+}
+
+export function loadGoogleConfig(): GoogleConfig {
+    return {
+        clientId: process.env.GOOGLE_CLIENT_ID,
+        clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+        callbackUrl: process.env.GOOGLE_CALLBACK_URL ?? 'http://localhost:5001/api/v1/auth/callback',
+    };
+}

package/src/controllers/authController.ts

@@ -0,0 +1,237 @@
+import { Router, type CookieOptions, type Request, type Response } from 'express';
+import { randomBytes } from 'node:crypto';
+import type { IAuthManager } from '../managers/types.js';
+import type { IOidcProvider } from '../oidc/types.js';
+import { type AuthConfig, OAUTH_COOKIE, SESSION_COOKIE } from '../config.js';
+
+/** The OAuth state/PKCE cookie only needs to outlive the redirect round-trip. */
+const OAUTH_COOKIE_TTL_MS = 10 * 60 * 1000;
+
+/**
+ * HTTP surface for client authentication (BFF cookie model).
+ *
+ * The session JWT rides in an httpOnly cookie ({@link SESSION_COOKIE}) — the
+ * browser never sees it in JS — so endpoints derive identity from the cookie and
+ * the UI learns who it is via `GET /auth/me`.
+ *
+ * Mounted under `/auth`:
+ *   POST /auth/guest    -> mint a guest session; set the session cookie
+ *   POST /auth/refresh  -> roll the session cookie forward
+ *   GET  /auth/validate -> verify the cookie; X-Client-Id / X-Guest (gateway ForwardAuth)
+ *   GET  /auth/me       -> { clientId, guest, email? } for the UI
+ *   GET  /auth/login    -> begin Authorization Code + PKCE; redirect to the provider
+ *   GET  /auth/callback -> finish login; promote the guest in place; set the session cookie
+ *   POST /auth/logout   -> clear the session cookie (UI then mints a fresh guest)
+ */
+export class AuthController {
+    public readonly router: Router;
+
+    public constructor(
+        private readonly manager: IAuthManager,
+        private readonly oidc: IOidcProvider,
+        private readonly config: AuthConfig,
+    ) {
+        this.router = Router();
+        this.registerRoutes();
+    }
+
+    private registerRoutes(): void {
+        this.router.post('/guest', this.createGuestSession);
+        this.router.post('/refresh', this.refreshSession);
+        this.router.get('/validate', this.validate);
+        this.router.get('/me', this.me);
+        this.router.get('/login', this.login);
+        this.router.get('/callback', this.callback);
+        this.router.post('/logout', this.logout);
+    }
+
+    private readonly createGuestSession = async (req: Request, res: Response): Promise<void> => {
+        // Idempotent: if a valid session already exists (guest OR authenticated),
+        // return it instead of minting a new guest — so this can never downgrade a
+        // logged-in user or churn an existing guest. To abandon a session, use
+        // POST /auth/logout (which clears the cookie); the next call then creates one.
+        const existing = this.sessionToken(req);
+        if (existing) {
+            try {
+                const claims = await this.manager.validate(existing);
+                res.status(200).json({ clientId: claims.sub, guest: claims.guest });
+                return;
+            } catch {
+                // Invalid/expired cookie -> fall through and mint a fresh guest.
+            }
+        }
+
+        const session = await this.manager.createGuestSession();
+        this.setSessionCookie(res, session.token, session.expiresAt);
+        res.status(201).json({ clientId: session.clientId, guest: true });
+    };
+
+    private readonly refreshSession = async (req: Request, res: Response): Promise<void> => {
+        const token = this.sessionToken(req);
+        if (!token) {
+            res.status(401).json({ error: 'no session' });
+            return;
+        }
+
+        try {
+            const session = await this.manager.refreshSession(token);
+            this.setSessionCookie(res, session.token, session.expiresAt);
+            const claims = await this.manager.validate(session.token);
+            res.status(200).json({ clientId: claims.sub, guest: claims.guest });
+        } catch {
+            this.clearSessionCookie(res);
+            res.status(401).json({ error: 'invalid or expired session' });
+        }
+    };
+
+    private readonly validate = async (req: Request, res: Response): Promise<void> => {
+        const token = this.sessionToken(req);
+        if (!token) {
+            res.status(401).json({ error: 'no session' });
+            return;
+        }
+
+        try {
+            const claims = await this.manager.validate(token);
+            // The gateway (ForwardAuth) copies these onto the proxied request so
+            // downstream services receive a trusted identity they didn't have to verify.
+            res.setHeader('X-Client-Id', claims.sub);
+            res.setHeader('X-Guest', String(claims.guest));
+            res.status(200).json({ clientId: claims.sub, guest: claims.guest });
+        } catch {
+            res.status(401).json({ error: 'invalid or expired session' });
+        }
+    };
+
+    private readonly me = async (req: Request, res: Response): Promise<void> => {
+        const token = this.sessionToken(req);
+        if (!token) {
+            res.status(401).json({ error: 'no session' });
+            return;
+        }
+
+        try {
+            const info = await this.manager.describeSession(token);
+            res.status(200).json(info);
+        } catch {
+            res.status(401).json({ error: 'invalid or expired session' });
+        }
+    };
+
+    private readonly login = async (_req: Request, res: Response): Promise<void> => {
+        // Generic, provider-agnostic CSRF state + PKCE verifier; the provider turns
+        // the verifier into a code_challenge when building the authorize URL.
+        const state = randomBytes(16).toString('base64url');
+        const codeVerifier = randomBytes(32).toString('base64url');
+
+        try {
+            const url = await this.oidc.authorizeUrl(state, codeVerifier);
+            res.cookie(OAUTH_COOKIE, JSON.stringify({ state, codeVerifier }), {
+                ...this.baseCookieOptions(),
+                // path '/' (not the mount path) so it survives wherever the auth
+                // routes are mounted; it's short-lived, signed and single-use.
+                maxAge: OAUTH_COOKIE_TTL_MS,
+                signed: true,
+            });
+            res.redirect(302, url);
+        } catch {
+            res.status(503).json({ error: 'login not configured' });
+        }
+    };
+
+    private readonly callback = async (req: Request, res: Response): Promise<void> => {
+        const code = typeof req.query.code === 'string' ? req.query.code : undefined;
+        const state = typeof req.query.state === 'string' ? req.query.state : undefined;
+        const stash = this.readOauthCookie(req);
+
+        // The OAuth cookie is single-use.
+        res.clearCookie(OAUTH_COOKIE, { path: '/' });
+
+        if (!code || !state || !stash || stash.state !== state) {
+            res.status(400).json({ error: 'invalid oauth callback' });
+            return;
+        }
+
+        try {
+            // Pass ALL callback params (code, state, iss, …) through to the provider.
+            const queryIndex = req.originalUrl.indexOf('?');
+            const callbackParams = new URLSearchParams(
+                queryIndex >= 0 ? req.originalUrl.slice(queryIndex + 1) : '',
+            );
+            const identity = await this.oidc.exchangeCode(callbackParams, stash.codeVerifier);
+            // Promote the current guest in place if one is present on this device.
+            const guestClientId = await this.guestClientId(req);
+            const resolved = await this.manager.resolveLogin(identity, guestClientId);
+
+            const session = await this.manager.createAuthenticatedSession(resolved.clientId);
+            // Overwriting the session cookie also "clears" the guest session.
+            this.setSessionCookie(res, session.token, session.expiresAt);
+            res.redirect(302, this.config.uiRedirectUrl);
+        } catch (e) {
+            console.log(e);
+            res.status(400).json({ error: 'login failed' });
+        }
+    };
+
+    private readonly logout = async (_req: Request, res: Response): Promise<void> => {
+        this.clearSessionCookie(res);
+        res.status(204).end();
+    };
+
+    // --- cookie helpers ---
+
+    private baseCookieOptions(): CookieOptions {
+        return {
+            httpOnly: true,
+            sameSite: 'lax',
+            secure: this.config.secureCookies,
+            path: '/',
+        };
+    }
+
+    private setSessionCookie(res: Response, token: string, expiresAt: number): void {
+        res.cookie(SESSION_COOKIE, token, {
+            ...this.baseCookieOptions(),
+            maxAge: Math.max(0, expiresAt * 1000 - Date.now()),
+        });
+    }
+
+    private clearSessionCookie(res: Response): void {
+        res.clearCookie(SESSION_COOKIE, { path: '/' });
+    }
+
+    private sessionToken(req: Request): string | undefined {
+        const value = req.cookies?.[SESSION_COOKIE];
+        return typeof value === 'string' && value.length > 0 ? value : undefined;
+    }
+
+    private readOauthCookie(req: Request): { state: string; codeVerifier: string } | undefined {
+        const raw = req.signedCookies?.[OAUTH_COOKIE];
+        if (typeof raw !== 'string') {
+            return undefined;
+        }
+        try {
+            const parsed = JSON.parse(raw) as { state?: unknown; codeVerifier?: unknown };
+            if (typeof parsed.state === 'string' && typeof parsed.codeVerifier === 'string') {
+                return { state: parsed.state, codeVerifier: parsed.codeVerifier };
+            }
+        } catch {
+            // fall through
+        }
+        return undefined;
+    }
+
+    /** The current session's clientId iff it is a (still valid) guest — for promote-in-place. */
+    private async guestClientId(req: Request): Promise<string | undefined> {
+        const token = this.sessionToken(req);
+        if (!token) {
+            return undefined;
+        }
+        try {
+            const claims = await this.manager.validate(token);
+            return claims.guest ? claims.sub : undefined;
+        } catch {
+            return undefined;
+        }
+    }
+}