@owlmeans/auth-common 0.1.18-rc.8 → 0.1.18

package/src/types.ts

@@ -42,5 +42,72 @@ export interface ProfileToEntityIdRequest {
 }
 
 export interface ProfileToEntityIdResponse {
-  entityId: string
+  entitySlug: string
+}
+
+/**
+ * An organization entity: one immutable id, one renameable slug, and the trail of slugs it used to
+ * answer to.
+ *
+ * `formerSlugs` is what makes a rename survivable rather than merely possible. Tokens minted before
+ * the rename keep arriving until they expire, and third-party systems keep quoting the old value
+ * indefinitely; resolving a former slug to the same entity is how both keep working without anyone
+ * reissuing anything.
+ */
+export interface OrgEntityRef {
+  id: string
+  slug: string
+  formerSlugs?: string[]
+  /** Frozen identifier for systems whose names cannot be rewritten. See `ResolvedEntity.iamKey`. */
+  iamKey: string
+}
+
+/**
+ * Resolves the renameable slug on a token to the stable entity it names.
+ *
+ * Registered only by implementations that actually store organizations. Basic auth deliberately
+ * does not define what an entity id is — a deployment backed by an external IAM has no such record
+ * and registers nothing, and every consumer must therefore treat an unresolved entity as ordinary
+ * rather than exceptional.
+ */
+export interface EntityResolverService extends InitializedService {
+  /**
+   * Find an entity by any name it has ever answered to: its id, its current slug, a former slug,
+   * or its frozen `iamKey`. Ids win over slugs, so a slug that collides with some other entity's
+   * id can never shadow it.
+   */
+  resolve: (value: string) => Promise<OrgEntityRef | null>
+  byId: (id: string) => Promise<OrgEntityRef | null>
+  /** Mint an unused slug. Uniqueness is settled against the store, not by entropy. */
+  mintSlug: () => Promise<string>
+  /**
+   * Point the entity at a new slug, retiring the old one into `formerSlugs`.
+   *
+   * This is the whole cost of a rename: nothing else in any store is touched, because nothing else
+   * keys on the slug.
+   */
+  rename: (id: string, slug: string) => Promise<OrgEntityRef>
+  /**
+   * Read — or, on first ask, mint and persist — a name this entity is known by in a system that
+   * cannot be renamed later (a namespace, a bucket prefix, a realm).
+   *
+   * Minting through the entity record rather than deriving the name on demand is what lets the
+   * slug move afterwards: the derivation happens once, the result is what everything addresses,
+   * and a later rename leaves the live resource alone.
+   */
+  mintName: (id: string, key: string, mint: (entity: OrgEntityRef) => string) => Promise<string>
+}
+
+/**
+ * What the surrogate login window is told about why it was opened.
+ *
+ * Every field is optional: the window must render something sensible when opened by hand, or by an
+ * older build that knew none of these parameters. `next` carries the address to run once the
+ * window is one level up, so the flow parameters the opener's URL held are forwarded rather than
+ * silently dropped.
+ */
+export interface SurrogateQuery {
+  intent?: string
+  next?: string
+  method?: string
 }

package/src/utils/trusted.ts

@@ -1,17 +1,18 @@
 
 import type { Context, Config } from './types.js'
 import type { TrustedRecord } from '../types.js'
-import type { Resource } from '@owlmeans/resource'
-import { fromPubKey, makeKeyPairModel } from '@owlmeans/basic-keys'
+import type { Criteria, Resource } from '@owlmeans/resource'
+import { keyHelper, makeKeyPairModel } from '@owlmeans/basic-keys'
 
 export const trust = async <C extends Config, T extends Context<C>>(context: T, resource: string, userName: string, field: string = 'name') => {
-  const trustedUser = await context.resource<Resource<TrustedRecord>>(resource).load(userName, field)
+  const where: Criteria<TrustedRecord> = { [field]: userName }
+  const trustedUser = await context.resource<Resource<TrustedRecord>>(resource).load(where)
   if (trustedUser == null) {
     throw new SyntaxError(`Auth service trusted entity is not provided: ${userName}`)
   }
 
   // @TODO credential can really be undefined - we need to process it properly
-  const keyPair = trustedUser.secret != null ? makeKeyPairModel(trustedUser.secret) : fromPubKey(trustedUser.credential!)
+  const keyPair = trustedUser.secret != null ? makeKeyPairModel(trustedUser.secret) : keyHelper.fromPubKey(trustedUser.credential!)
 
   return { user: trustedUser, key: keyPair }
 }

package/tests/basic-ed25519.spec.ts

@@ -0,0 +1,99 @@
+import { describe, expect, test } from 'bun:test'
+import { AuthenPayloadError, AuthroizationType } from '@owlmeans/auth'
+import {
+  BED255_NONCE_HEADER, BED255_SIG_TTL, BED255_TIME_HEADER, makeBasicEd25519Guard,
+  makeResourceSignedRequestReplayStore
+} from '@owlmeans/auth-common'
+import type { BasicEd25519Guard, SignedRequestReplayResource } from '@owlmeans/auth-common'
+import type { AbstractRequest, AbstractResponse } from '@owlmeans/entrypoint'
+import type { Auth } from '@owlmeans/auth'
+import { RecordExists } from '@owlmeans/resource'
+import { makeTrustFixture, TRUSTED_ALIAS } from './context.js'
+
+const timeKey = BED255_TIME_HEADER.toLowerCase()
+const nonceKey = BED255_NONCE_HEADER.toLowerCase()
+
+const request = async (timestamp: string, nonce: string) => {
+  const fixture = makeTrustFixture({ withSecret: true, name: 'auth-common-tests' })
+  const body = { action: 'publish' }
+  const signature = await fixture.authKey.sign({
+    body,
+    headers: { [timeKey]: timestamp, [nonceKey]: nonce }
+  })
+  const req = {
+    alias: 'signed', body, headers: {
+      [timeKey]: timestamp,
+      [nonceKey]: nonce,
+      authorization: `${AuthroizationType.Ed25519BasicSignature.toUpperCase()} `
+        + `Credential=${fixture.authRecord.id} Signature=${signature}`,
+    }, params: {}, query: {}, path: '/signed'
+  } satisfies AbstractRequest
+  const guard = makeBasicEd25519Guard(TRUSTED_ALIAS)
+  fixture.ctx.registerService(guard)
+
+  return { fixture, guard, req }
+}
+
+const handle = async (
+  guard: BasicEd25519Guard, req: AbstractRequest
+): Promise<Auth | undefined> => {
+  let value: Auth | undefined
+  const response: AbstractResponse<Auth> = {
+    resolve: resolved => { value = resolved },
+    reject: error => { throw error }
+  }
+  await guard.handle(req, response)
+  return value
+}
+
+describe('@owlmeans/auth-common — signed request freshness and replay protection', () => {
+  test('accepts a canonical current timestamp once and rejects the replay by default', async () => {
+    const signed = await request(new Date().toISOString(), 'one-use-nonce')
+
+    expect((await handle(signed.guard, signed.req))?.userId).toBe(signed.fixture.authRecord.id)
+    await expect(handle(signed.guard, signed.req)).rejects.toBeInstanceOf(AuthenPayloadError)
+  })
+
+  test('rejects parseable but non-canonical timestamps', async () => {
+    const signed = await request(new Date().toUTCString(), 'non-canonical')
+
+    await expect(handle(signed.guard, signed.req)).rejects.toBeInstanceOf(AuthenPayloadError)
+  })
+
+  test('rejects timestamps outside the symmetric 60-second window', async () => {
+    const past = await request(new Date(Date.now() - BED255_SIG_TTL - 1_000).toISOString(), 'past')
+    const future = await request(new Date(Date.now() + BED255_SIG_TTL + 1_000).toISOString(), 'future')
+
+    await expect(handle(past.guard, past.req)).rejects.toBeInstanceOf(AuthenPayloadError)
+    await expect(handle(future.guard, future.req)).rejects.toBeInstanceOf(AuthenPayloadError)
+  })
+
+  test('rejects authentication when an injected replay store fails', async () => {
+    const signed = await request(new Date().toISOString(), 'store-failure')
+    const guard = makeBasicEd25519Guard(TRUSTED_ALIAS, {
+      replay: { claim: async () => { throw new Error('store unavailable') } }
+    })
+    signed.fixture.ctx.registerService(guard)
+
+    await expect(handle(guard, signed.req)).rejects.toBeInstanceOf(AuthenPayloadError)
+  })
+
+  test('adapts a create-once resource and forwards the absolute signed expiry', async () => {
+    let claimed = false
+    let observedExpiry: Date | undefined
+    const resource = {
+      create: async (record: { id?: string }, opts?: { ttl?: number | Date }) => {
+        if (claimed) throw new RecordExists(record.id ?? '')
+        claimed = true
+        observedExpiry = opts?.ttl as Date
+        return record
+      }
+    } as SignedRequestReplayResource
+    const replay = makeResourceSignedRequestReplayStore(resource)
+    const expiresAt = new Date(Date.now() + BED255_SIG_TTL)
+
+    expect(await replay.claim('service:nonce', expiresAt)).toBe(true)
+    expect(observedExpiry).toBe(expiresAt)
+    expect(await replay.claim('service:nonce', expiresAt)).toBe(false)
+  })
+})

package/tests/context.ts

@@ -1,4 +1,4 @@
-import { AppType, Layer, makeBasicContext } from '@owlmeans/context'
+import { AppType, makeBasicContext } from '@owlmeans/context'
 import type { BasicConfig, BasicContext } from '@owlmeans/context'
 import { makeMemoryTrustedResource, makeFixtureKeyPair } from '@owlmeans/test-auth'
 import type { TrustedRecord } from '@owlmeans/auth-common'
@@ -38,7 +38,6 @@ export const makeTrustFixture = (
   const ctx = makeBasicContext<BasicConfig>({
     ready: false,
     service: 'auth-common-tests',
-    layer: Layer.Service,
     type: AppType.Backend,
   })
 

package/tests/dispatcher.spec.ts

@@ -1,38 +1,38 @@
 import { describe, expect, test } from 'bun:test'
-import { modules } from '@owlmeans/auth-common'
+import { authProtocols } from '@owlmeans/auth-common'
 import { DISPATCHER, DISPATCHER_AUTHEN } from '@owlmeans/auth'
 import { DISPATCHER_PATH } from '../src/consts.js'
 
-// The DISPATCHER module intentionally declares service: DISPATCHER so that
-// urlCall() produces an absolute URL (pointing to the auth service).
+// The DISPATCHER entrypoint intentionally declares service: DISPATCHER so that
+// url() produces an absolute URL (pointing to the auth service).
 // The fix for the React Router 404 ("/https:/vib.owl.flat/dispatcher") lives
 // in @owlmeans/client's navigator.navigate() — when the URL is absolute it
 // does a browser redirect (globalThis.location.href) instead of React Router navigate().
 
-describe('@owlmeans/auth-common — DISPATCHER module declaration', () => {
-  const dispatcher = modules.find(m => m.route.route.alias === DISPATCHER)
+describe('@owlmeans/auth-common — DISPATCHER protocol declaration', () => {
+  const dispatcher = authProtocols.dispatcher
 
-  test('DISPATCHER module is present in the modules array', () => {
-    expect(dispatcher).toBeDefined()
+  test('DISPATCHER protocol is present in the authentication tree', () => {
+    expect(dispatcher.alias).toBe(DISPATCHER)
   })
 
   test('DISPATCHER route has an explicit service override (cross-service)', () => {
     // service: DISPATCHER is intentional — the dispatcher belongs to the auth service.
     // The navigator in @owlmeans/client handles the resulting absolute URL correctly.
-    expect(dispatcher?.route.route.service).toBe(DISPATCHER)
+    expect(dispatcher.route.route.service).toBe(DISPATCHER)
   })
 
   test('DISPATCHER route path is DISPATCHER_PATH (/dispatcher)', () => {
-    expect(dispatcher?.route.route.path).toBe(DISPATCHER_PATH)
+    expect(dispatcher.route.route.path).toBe(DISPATCHER_PATH)
   })
 
-  test('DISPATCHER module is sticky (always registered in every app router)', () => {
-    expect(dispatcher?.sticky).toBe(true)
+  test('DISPATCHER entrypoint is sticky (always registered in every app router)', () => {
+    expect(dispatcher.sticky).toBe(true)
   })
 
-  test('DISPATCHER_AUTHEN backend module is distinct', () => {
-    const dispatcherAuthen = modules.find(m => m.route.route.alias === DISPATCHER_AUTHEN)
-    expect(dispatcherAuthen).toBeDefined()
-    expect(dispatcherAuthen?.sticky).toBeFalsy()
+  test('DISPATCHER_AUTHEN backend entrypoint is distinct', () => {
+    const dispatcherAuthen = authProtocols.dispatcherAuthenticate
+    expect(dispatcherAuthen.alias).toBe(DISPATCHER_AUTHEN)
+    expect(dispatcherAuthen.sticky).toBeFalsy()
   })
 })

package/tests/entity.spec.ts

@@ -0,0 +1,112 @@
+import { describe, expect, test } from 'bun:test'
+import { AppType, createService, makeBasicContext } from '@owlmeans/context'
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import { AuthenFailed, AuthRole } from '@owlmeans/auth'
+import type { Auth } from '@owlmeans/auth'
+import type { AbstractRequest, ResolvedEntity } from '@owlmeans/entrypoint'
+import { makeEntityScope } from '../src/entity.js'
+import { ENTITY_RESOLVER } from '../src/consts.js'
+import type { EntityResolverService, OrgEntityRef } from '../src/types.js'
+
+const ACME: OrgEntityRef = { id: '0123456789abcdef01234567', slug: 'acme', formerSlugs: ['acme-old'], iamKey: 'acme-key' }
+
+/** A context with an in-memory registry of one organization, or none at all. */
+const contextWith = async (registry?: OrgEntityRef[]) => {
+  const ctx = makeBasicContext<BasicConfig>({ ready: false, service: 'entity-tests', type: AppType.Backend })
+  const calls: string[] = []
+  if (registry != null) {
+    ctx.registerService(createService<EntityResolverService>(ENTITY_RESOLVER, {
+      resolve: async value => {
+        calls.push(value)
+        return registry.find(entity => entity.id === value || entity.slug === value
+          || entity.formerSlugs?.includes(value) || entity.iamKey === value) ?? null
+      },
+      byId: async id => registry.find(entity => entity.id === id) ?? null,
+      mintSlug: async () => 'minted',
+      rename: async () => { throw new Error('not used') },
+      mintName: async () => { throw new Error('not used') },
+    }))
+  }
+  ctx.configure()
+  await ctx.init()
+
+  return { ctx: ctx as BasicContext<BasicConfig>, calls }
+}
+
+const requestFor = (entitySlug?: string, entity?: ResolvedEntity): AbstractRequest => ({
+  alias: 'any', path: '/', params: {}, query: {}, headers: {},
+  auth: { token: 't', type: 'oidc', userId: 'u', role: AuthRole.User, scopes: [], isUser: true,
+    createdAt: new Date(), ...(entitySlug != null ? { entitySlug } : {}) } as Auth,
+  ...(entity != null ? { entity } : {}),
+})
+
+const attached: ResolvedEntity = { id: 'iam-key-tenant', slug: 'tenant', iamKey: 'iam-key-tenant' }
+
+describe('attachEntity — an entity the guard attached', () => {
+  test('is kept when its slug is the token one, with no resolver registered', async () => {
+    const { ctx } = await contextWith()
+    const request = requestFor('tenant', attached)
+
+    expect(await makeEntityScope(request).attachEntity(ctx)).toEqual(attached)
+    expect(request.entity).toEqual(attached)
+  })
+
+  test('is kept without asking a registered resolver', async () => {
+    const { ctx, calls } = await contextWith([ACME])
+    const request = requestFor('tenant', attached)
+
+    expect(await makeEntityScope(request).attachEntity(ctx)).toEqual(attached)
+    expect(calls).toEqual([])
+  })
+
+  test('with another slug falls through to the resolver', async () => {
+    const { ctx, calls } = await contextWith([ACME])
+    const request = requestFor('acme', attached)
+
+    expect(await makeEntityScope(request).attachEntity(ctx)).toEqual(ACME)
+    expect(request.entity).toEqual(ACME)
+    expect(calls).toEqual(['acme'])
+  })
+
+  test('with another slug and no resolver is dropped, never trusted', async () => {
+    const { ctx } = await contextWith()
+    const request = requestFor('acme', attached)
+
+    expect(await makeEntityScope(request).attachEntity(ctx)).toBeUndefined()
+    expect(request.entity).toBeUndefined()
+  })
+
+  test('on a token naming no organization is dropped', async () => {
+    const { ctx } = await contextWith()
+    const request = requestFor(undefined, attached)
+
+    expect(await makeEntityScope(request).attachEntity(ctx)).toBeUndefined()
+    expect(request.entity).toBeUndefined()
+  })
+})
+
+describe('attachEntity — the resolver path', () => {
+  test('resolves and canonicalizes a retired slug', async () => {
+    const { ctx } = await contextWith([ACME])
+    const request = requestFor('acme-old')
+
+    expect(await makeEntityScope(request).attachEntity(ctx)).toEqual(ACME)
+    expect(request.entity).toEqual(ACME)
+    expect(request.auth?.entitySlug).toBe('acme')
+  })
+
+  test('refuses a token naming an organization the registry does not know', async () => {
+    const { ctx } = await contextWith([ACME])
+
+    await expect(makeEntityScope(requestFor('nobody')).attachEntity(ctx)).rejects.toBeInstanceOf(AuthenFailed)
+  })
+
+  test('is a no-op with no resolver and nothing attached', async () => {
+    const { ctx } = await contextWith()
+    const request = requestFor('acme')
+
+    expect(await makeEntityScope(request).attachEntity(ctx)).toBeUndefined()
+    expect(request.entity).toBeUndefined()
+    expect(request.auth?.entitySlug).toBe('acme')
+  })
+})

package/src/modules.ts

@@ -1,53 +0,0 @@
-
-import {
-  AUTHEN, AUTHEN_AUTHEN, AUTHEN_INIT, AUTHEN_RELY, AllowanceRequestSchema, AuthCredentialsSchema,
-  AuthTokenSchema, CAUTHEN, CAUTHEN_AUTHEN, CAUTHEN_AUTHEN_DEFAULT, CAUTHEN_AUTHEN_TYPED, DISPATCHER,
-  DISPATCHER_AUTHEN, OptionalAuthTokenSchema, CAUTHEN_FLOW_ENTER
-} from '@owlmeans/auth'
-// import { AppType } from '@owlmeans/context'
-import { body, filter, entrypoint, query } from '@owlmeans/entrypoint'
-import { route, RouteMethod, frontend, backend, socket } from '@owlmeans/route'
-import { DISPATCHER_PATH, WEB_API, authApi } from './consts.js'
-
-export const modules = [
-  entrypoint(route(AUTHEN, '/authentication', backend())),
-  entrypoint(route(AUTHEN_INIT, '/init', backend(AUTHEN, RouteMethod.POST)), filter(body(AllowanceRequestSchema))),
-  entrypoint(route(AUTHEN_AUTHEN, '/authenticate', backend(AUTHEN, RouteMethod.POST)), filter(body(AuthCredentialsSchema))),
-  entrypoint(route(AUTHEN_RELY, '/rely', socket(AUTHEN)), filter(query(OptionalAuthTokenSchema))),
-  entrypoint(route(CAUTHEN, '/authentication', frontend())),
-  entrypoint(route(CAUTHEN_AUTHEN, '/login', frontend(CAUTHEN))),
-  entrypoint(route(CAUTHEN_AUTHEN_DEFAULT, '/', frontend(CAUTHEN_AUTHEN, true))),
-  entrypoint(route(CAUTHEN_AUTHEN_TYPED, '/:type', frontend(CAUTHEN_AUTHEN))),
-  // This is a helper route that is used by service providers to redirect to an external authentication service.
-  entrypoint(route(CAUTHEN_FLOW_ENTER, '/', frontend())),
-  // This is a helper route that is useb by service providres to process authentication provisioning via redirect.
-  // Also it can be default starting point to be redirected to an external identity provider.
-  entrypoint(
-    route(DISPATCHER, DISPATCHER_PATH, frontend({ service: DISPATCHER })),
-    // This module is sticky - it means it's always attach to client router.
-    // It's required here cause every web app needs dispatcher route to authorize
-    // rediected users.
-    filter(query(AuthTokenSchema), { sticky: true })
-  ),
-  // This is a helper route that representes a API endpoint of service provider that wants to authenticate
-  // a user with OwlMeans server-auth library.
-  entrypoint(route(DISPATCHER_AUTHEN, '/authenticate', backend(null, RouteMethod.POST)), filter(body(AuthTokenSchema))),
-]
-
-export const managerModules = [
-  entrypoint(route(authApi.profile.base, '/profile', backend({ service: WEB_API }))),
-  entrypoint(route(
-    authApi.profile.toEntityId, '/to-entity-id',
-    backend(authApi.profile.base, RouteMethod.POST)
-  )),
-  entrypoint(route(authApi.auth.base, '/auth', backend({ service: WEB_API }))),
-  entrypoint(route(
-    authApi.auth.delegate, '/delegate',
-    backend(authApi.auth.base, RouteMethod.POST)
-  )),
-]
-
-// const skipModules = [DISPATCHER]
-// export const authBackendModules = modules.filter(
-//   module => !skipModules.includes(module.alias) && module.route.route.type === AppType.Backend
-// ).map(module => module.alias)