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

package/build/utils/trusted.js

@@ -1,11 +1,12 @@
-import { fromPubKey, makeKeyPairModel } from '@owlmeans/basic-keys';
+import { keyHelper, makeKeyPairModel } from '@owlmeans/basic-keys';
 export const trust = async (context, resource, userName, field = 'name') => {
-    const trustedUser = await context.resource(resource).load(userName, field);
+    const where = { [field]: userName };
+    const trustedUser = await context.resource(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 };
 };
 //# sourceMappingURL=trusted.js.map

package/build/utils/trusted.js.map

@@ -1 +1 @@
-{"version":3,"file":"trusted.js","sourceRoot":"","sources":["../../src/utils/trusted.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAEnE,MAAM,CAAC,MAAM,KAAK,GAAG,KAAK,EAA0C,OAAU,EAAE,QAAgB,EAAE,QAAgB,EAAE,KAAK,GAAW,MAAM,EAAE,EAAE;IAC5I,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,QAAQ,CAA0B,QAAQ,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;IACnG,IAAI,WAAW,IAAI,IAAI,EAAE,CAAC;QACxB,MAAM,IAAI,WAAW,CAAC,gDAAgD,QAAQ,EAAE,CAAC,CAAA;IACnF,CAAC;IAED,4EAA4E;IAC5E,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,UAAW,CAAC,CAAA;IAEvH,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,EAAE,CAAA;AAC5C,CAAC,CAAA"}
+{"version":3,"file":"trusted.js","sourceRoot":"","sources":["../../src/utils/trusted.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAElE,MAAM,CAAC,MAAM,KAAK,GAAG,KAAK,EAA0C,OAAU,EAAE,QAAgB,EAAE,QAAgB,EAAE,KAAK,GAAW,MAAM,EAAE,EAAE;IAC5I,MAAM,KAAK,GAA4B,EAAE,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAA;IAC5D,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,QAAQ,CAA0B,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACzF,IAAI,WAAW,IAAI,IAAI,EAAE,CAAC;QACxB,MAAM,IAAI,WAAW,CAAC,gDAAgD,QAAQ,EAAE,CAAC,CAAA;IACnF,CAAC;IAED,4EAA4E;IAC5E,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,WAAW,CAAC,UAAW,CAAC,CAAA;IAEjI,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,EAAE,CAAA;AAC5C,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/auth-common",
-  "version": "0.1.18-rc.8",
+  "version": "0.1.18",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -29,20 +29,20 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.18-rc.6",
-    "@owlmeans/auth-common": "^0.1.18-rc.8",
-    "@owlmeans/basic-ids": "^0.1.18-rc.6",
-    "@owlmeans/basic-keys": "^0.1.18-rc.8",
-    "@owlmeans/client-entrypoint": "^0.1.18-rc.8",
-    "@owlmeans/context": "^0.1.18-rc.6",
-    "@owlmeans/entrypoint": "^0.1.18-rc.7",
-    "@owlmeans/resource": "^0.1.18-rc.7",
-    "@owlmeans/route": "^0.1.18-rc.6"
+    "@owlmeans/auth": "^0.1.18",
+    "@owlmeans/auth-common": "^0.1.18",
+    "@owlmeans/basic-ids": "^0.1.18",
+    "@owlmeans/basic-keys": "^0.1.18",
+    "@owlmeans/client-entrypoint": "^0.1.18",
+    "@owlmeans/context": "^0.1.18",
+    "@owlmeans/entrypoint": "^0.1.18",
+    "@owlmeans/resource": "^0.1.18",
+    "@owlmeans/route": "^0.1.18"
   },
   "devDependencies": {
-    "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/test-auth": "^0.1.18-rc.8",
-    "@types/bun": "^1.3.14",
+    "@owlmeans/dep-config": "^0.1.18",
+    "@owlmeans/test-auth": "^0.1.18",
+    "@types/bun": "^1.4.2",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },

package/src/consts.ts

@@ -8,6 +8,15 @@ export const RELY_ACTION_TIMEOUT = 600
 
 export const DISPATCHER_PATH = '/dispatcher'
 
+/**
+ * Where the surrogate login window runs.
+ *
+ * Reserved exactly like {@link DISPATCHER_PATH}: an application must not declare a route of its
+ * own here, and a code generator must not produce one. It is user-visible — it is what the popup's
+ * address bar shows.
+ */
+export const SURROGATE_PATH = '/surrogate'
+
 export const DEF_AUTH_SRV = 'auth'
 
 export const DEFAULT_GUARD = DEF_AUTH_SRV
@@ -16,6 +25,19 @@ export const TOKEN_UPDATE = 'auth-token-refresh'
 
 export const WEB_API = 'web-auth-api'
 
+/** Service alias of the organization-entity resolver, when an implementation registers one. */
+export const ENTITY_RESOLVER = 'entity-resolver'
+
+/**
+ * What an organization slug may look like: a DNS label, lowercase.
+ *
+ * The constraint is not cosmetic. The same slug is used to compose hostnames, Kubernetes object
+ * names and OIDC client ids, so anything that would need sanitising before it could address one of
+ * those is rejected at the point it is chosen instead — a slug that survives this pattern passes
+ * through every downstream name unchanged.
+ */
+export const ENTITY_SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])?$/
+
 export const authApi = {
   profile: {
     base: 'api:profile',
@@ -36,3 +58,13 @@ export const authApi = {
   },
 }
 
+
+/**
+ * The request header an authenticated call carries, re-exported for the packages that only depend
+ * on this half of the vocabulary.
+ *
+ * One spelling, one home: it is declared by `@owlmeans/auth` and named here so a client-side
+ * package does not have to take a dependency on the whole auth package to recognise its own
+ * bearer on a request it is about to send.
+ */
+export { AUTH_HEADER } from '@owlmeans/auth'

package/src/entity/types.ts

@@ -0,0 +1,52 @@
+import type { BasicContext } from '@owlmeans/context'
+import type { ResolvedEntity } from '@owlmeans/entrypoint'
+
+/** The organization entity one request acts for — built once at the top of a handler, never stored. */
+export interface EntityScope {
+  /**
+   * The value a handler should store and query organization-scoped records by.
+   *
+   * Prefers the entity's stable id, which is the whole point of resolving one: records keyed by it
+   * survive a rename untouched. Falls back to the slug on the token for deployments that register no
+   * resolver — there the slug IS the only identifier the system has, and refusing to serve them
+   * would break every installation backed by an external IAM.
+   *
+   * Never use this to compose a user-facing name (a hostname, a display label). Those want the
+   * current slug, `req.entity?.slug`, precisely because it can change.
+   */
+  entityKeyOf: () => string | undefined
+  /**
+   * `entityKeyOf` for handlers that cannot proceed without an organization.
+   *
+   * @throws {AuthorizationError} when the request carries no organization at all.
+   */
+  requireEntityKey: () => string
+  /**
+   * The full resolved entity, for handlers that need the slug or the frozen key as well as the id.
+   *
+   * @throws {AuthorizationError} when no resolver is registered or the entity did not resolve.
+   */
+  requireEntity: () => ResolvedEntity
+  /**
+   * Resolve the organization a just-authenticated request acts for, and attach it.
+   *
+   * Called wherever authentication is ESTABLISHED — the HTTP boundary, and any socket that
+   * authenticates on its own once the connection is already open. Both need it for the same reason:
+   * the token names the organization by a slug that can move, while everything downstream keys on
+   * the record. A path that authenticates without calling this leaves `request.entity` empty, and
+   * its handlers quietly fall back to comparing a slug against stored ids — which surfaces as "this
+   * project does not exist" rather than as a missing resolution, and costs an afternoon to find.
+   *
+   * An entity the guard already attached is kept while its slug is exactly the token's: a guard
+   * whose authority names the organization itself (an OIDC session of a tenanted client) is the only
+   * source such a deployment has, because the registry that owns the organization is not its own.
+   * One whose slug differs is never trusted — it is dropped, and resolution proceeds as if it had
+   * not been there.
+   *
+   * Otherwise a no-op when no resolver is registered: such a deployment has no organization store,
+   * and the slug is the only identifier it has.
+   *
+   * @throws {AuthenFailed} when the token names an organization that cannot be resolved.
+   */
+  attachEntity: (context: BasicContext<any>) => Promise<ResolvedEntity | undefined>
+}

package/src/entity.ts

@@ -0,0 +1,67 @@
+import type { AbstractRequest, ResolvedEntity } from '@owlmeans/entrypoint'
+import type { BasicContext } from '@owlmeans/context'
+import { AuthenFailed, AuthorizationError, authHelper } from '@owlmeans/auth'
+import type { EntityResolverService } from './types.js'
+import { ENTITY_RESOLVER } from './consts.js'
+import type { EntityScope } from './entity/types.js'
+
+export const makeEntityScope = (req: AbstractRequest): EntityScope => {
+  const entityKeyOf = (): string | undefined =>
+    req.entity?.id ?? authHelper.entitySlugOf(req.auth)
+
+  const requireEntityKey = (): string => {
+    const key = entityKeyOf()
+    if (key == null || key === '') {
+      throw new AuthorizationError()
+    }
+
+    return key
+  }
+
+  const requireEntity = (): ResolvedEntity => {
+    if (req.entity == null) {
+      throw new AuthorizationError()
+    }
+
+    return req.entity
+  }
+
+  const attachEntity = async (context: BasicContext<any>): Promise<ResolvedEntity | undefined> => {
+    const slug = authHelper.entitySlugOf(req.auth)
+    if (req.entity != null) {
+      if (slug != null && req.entity.slug === slug) {
+        return req.entity
+      }
+      req.entity = undefined
+    }
+
+    if (slug == null || !context.hasService(ENTITY_RESOLVER)) {
+      return undefined
+    }
+
+    const entity = await context.service<EntityResolverService>(ENTITY_RESOLVER).resolve(slug)
+    if (entity == null) {
+      throw new AuthenFailed('entity')
+    }
+
+    // Canonicalize: a request that arrived under a retired slug continues under the current one, so
+    // nothing echoing the value back can re-publish a name the organization has dropped.
+    req.auth!.entitySlug = entity.slug
+    req.entity = entity
+
+    return entity
+  }
+
+  return { entityKeyOf, requireEntityKey, requireEntity, attachEntity }
+}
+
+/** @deprecated compat:factory-refactor — use `makeEntityScope(req).entityKeyOf()` */
+export const entityKeyOf = (req: AbstractRequest): string | undefined => makeEntityScope(req).entityKeyOf()
+
+/** @deprecated compat:factory-refactor — use `makeEntityScope(req).requireEntityKey()` */
+export const requireEntityKey = (req: AbstractRequest): string => makeEntityScope(req).requireEntityKey()
+
+/** @deprecated compat:factory-refactor — use `makeEntityScope(request).attachEntity(context)` */
+export const attachEntity = async (
+  context: BasicContext<any>, request: AbstractRequest
+): Promise<ResolvedEntity | undefined> => await makeEntityScope(request).attachEntity(context)

package/src/entrypoints.ts

@@ -0,0 +1,68 @@
+
+import { AUTHEN, AUTHEN_AUTHEN, AUTHEN_INIT, AUTHEN_RELY, AllowanceRequestSchema, AuthCredentialsSchema, AuthTokenSchema, CAUTHEN, CAUTHEN_AUTHEN, CAUTHEN_AUTHEN_DEFAULT, CAUTHEN_AUTHEN_TYPED, DISPATCHER, DISPATCHER_AUTHEN, DISPATCHER_SURROGATE, OptionalAuthTokenSchema, CAUTHEN_FLOW_ENTER, type AllowanceRequest, type AllowanceResponse, type AuthCredentials, type AuthToken } from '@owlmeans/auth'
+// import { AppType } from '@owlmeans/context'
+import { contract, openProtocol, protocol, typed } from '@owlmeans/entrypoint'
+import { route, RouteMethod, frontend, backend, socket } from '@owlmeans/route'
+import { DISPATCHER_PATH, SURROGATE_PATH, WEB_API, authApi } from './consts.js'
+import { SurrogateQuerySchema } from './schemas.js'
+import type { SurrogateQuery } from './types.js'
+
+/** Shared authentication protocols, bound independently by server and browser packages. */
+export const authProtocols = {
+  authen: openProtocol(route(AUTHEN, '/authentication', backend())),
+  init: protocol(route(AUTHEN_INIT, '/init', backend(AUTHEN, RouteMethod.POST)),
+    contract.request({ body: typed<AllowanceRequest>(AllowanceRequestSchema) }, typed<AllowanceResponse>())),
+  authenticate: protocol(route(AUTHEN_AUTHEN, '/authenticate', backend(AUTHEN, RouteMethod.POST)),
+    contract.request({ body: typed<AuthCredentials>(AuthCredentialsSchema) }, typed<AuthToken>())),
+  rely: protocol(route(AUTHEN_RELY, '/rely', socket(AUTHEN)),
+    contract.request({ query: typed<Partial<AuthToken>>(OptionalAuthTokenSchema) }, typed<undefined>())),
+  client: openProtocol(route(CAUTHEN, '/authentication', frontend())),
+  login: openProtocol(route(CAUTHEN_AUTHEN, '/login', frontend(CAUTHEN))),
+  loginDefault: openProtocol(route(CAUTHEN_AUTHEN_DEFAULT, '/', frontend(CAUTHEN_AUTHEN, true))),
+  loginTyped: openProtocol(route(CAUTHEN_AUTHEN_TYPED, '/:type', frontend(CAUTHEN_AUTHEN))),
+  flowEnter: openProtocol(route(CAUTHEN_FLOW_ENTER, '/', frontend())),
+  dispatcher: protocol(
+    route(DISPATCHER, DISPATCHER_PATH, frontend({ service: DISPATCHER })),
+    contract.request({ query: typed<AuthToken>(AuthTokenSchema) }, typed()),
+    { sticky: true },
+  ),
+  // The login window an embedded application opens one level up.
+  //
+  // Top level and with no parent, so it renders outside every application layout — a popup must
+  // never show the application, with its navigation, inside itself. Sticky for the same reason the
+  // dispatcher is: it must attach to the client router regardless of service selection. It carries
+  // no `service`, unlike the dispatcher, because nothing server-side ever addresses it — the
+  // provider's callback goes to the dispatcher. And no guard: it is where a signed-out user lands.
+  surrogate: protocol(
+    route(DISPATCHER_SURROGATE, SURROGATE_PATH, frontend()),
+    contract.request({ query: typed<SurrogateQuery>(SurrogateQuerySchema) }, typed()),
+    { 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.
+  dispatcherAuthenticate: protocol(route(DISPATCHER_AUTHEN, '/authenticate', backend(null, RouteMethod.POST)),
+    contract.request({ body: typed<AuthToken>(AuthTokenSchema) }, typed<AuthToken>())),
+}
+
+/** Shared manager authentication protocols. */
+export const managerProtocols = {
+  profile: {
+    base: openProtocol(route(authApi.profile.base, '/profile', backend({ service: WEB_API }))),
+    toEntityId: openProtocol(route(
+    authApi.profile.toEntityId, '/to-entity-id',
+    backend(authApi.profile.base, RouteMethod.POST)
+    )),
+  },
+  auth: {
+    base: openProtocol(route(authApi.auth.base, '/auth', backend({ service: WEB_API }))),
+    delegate: openProtocol(route(
+    authApi.auth.delegate, '/delegate',
+    backend(authApi.auth.base, RouteMethod.POST)
+    )),
+  },
+}
+
+// const skipEntrypoints = [DISPATCHER]
+// export const authBackendEntrypoints = entrypoints.filter(
+//   module => !skipEntrypoints.includes(module.alias) && module.route.route.type === AppType.Backend
+// ).map(module => module.alias)

package/src/guards/basic-ed25519/consts.local.ts

@@ -0,0 +1,4 @@
+import { BED255_NONCE_HEADER, BED255_TIME_HEADER } from './consts.js'
+
+export const timeKey = BED255_TIME_HEADER.toLocaleLowerCase()
+export const nonceKey = BED255_NONCE_HEADER.toLocaleLowerCase()

package/src/guards/basic-ed25519/index.ts

@@ -1,4 +1,5 @@
 
 export type * from './types.js'
 export * from './consts.js'
+export * from './replay.js'
 export * from './service.js'

package/src/guards/basic-ed25519/replay.ts

@@ -0,0 +1,55 @@
+import { RecordExists } from '@owlmeans/resource'
+import type { SignedRequestReplayResource, SignedRequestReplayStore } from './types.js'
+
+/**
+ * Process-local replay protection used when a deployment has not supplied a shared resource.
+ * A timer removes each claim at its signed expiry, keeping the fallback bounded by the live
+ * replay window rather than by process lifetime.
+ */
+export const makeMemorySignedRequestReplayStore = (): SignedRequestReplayStore => {
+  const claims = new Map<string, number>()
+
+  return {
+    claim: async (id, expiresAt) => {
+      const now = Date.now()
+      const current = claims.get(id)
+      if (current != null && current > now) {
+        return false
+      }
+
+      const expiry = expiresAt.getTime()
+      claims.set(id, expiry)
+      const timer = setTimeout(() => {
+        if (claims.get(id) === expiry) {
+          claims.delete(id)
+        }
+      }, Math.max(0, expiry - now))
+      const unref = (timer as unknown as { unref?: () => void }).unref
+      unref?.call(timer)
+
+      return true
+    }
+  }
+}
+
+/**
+ * Adapt a create-once Resource to signed-request replay protection. Redis resources honour the
+ * absolute expiry and make the claim atomic across replicas (`SET NX`); other resource failures
+ * remain failures rather than being mistaken for successful claims.
+ */
+export const makeResourceSignedRequestReplayStore = (
+  resource: SignedRequestReplayResource
+): SignedRequestReplayStore => ({
+  claim: async (id, expiresAt) => {
+    try {
+      await resource.create({ id }, { ttl: expiresAt })
+      return true
+    } catch (error) {
+      if (error instanceof RecordExists
+        || (error as { type?: unknown } | null)?.type === RecordExists.typeName) {
+        return false
+      }
+      throw error
+    }
+  }
+})

package/src/guards/basic-ed25519/service.ts

@@ -1,32 +1,35 @@
 import { createService } from '@owlmeans/context'
 import type { AbstractRequest, AbstractResponse } from '@owlmeans/entrypoint'
 import { assertContext } from '@owlmeans/context'
-import {
-  BED255_NONCE_HEADER, BED255_TIME_HEADER, BED255_CASHE_RESOURCE, GUARD_ED25519,
-  BED255_SIG_TTL
-} from './consts.js'
+import { BED255_CASHE_RESOURCE, GUARD_ED25519, BED255_SIG_TTL } from './consts.js'
+import { nonceKey, timeKey } from './consts.local.js'
 import { trust } from '../../utils/trusted.js'
 import type { Config, Context } from '../../utils/types.js'
 import type { BasicEd25519Guard, BasicEd25519GuardOptions } from './types.js'
 import { AuthenPayloadError, AuthroizationType, AuthRole } from '@owlmeans/auth'
 import type { Auth } from '@owlmeans/auth'
 import { createIdOfLength } from '@owlmeans/basic-ids'
-import type { Resource, ResourceRecord } from '@owlmeans/resource'
 import { extractAuthToken } from '@owlmeans/auth-common/utils'
+import {
+  makeMemorySignedRequestReplayStore, makeResourceSignedRequestReplayStore
+} from './replay.js'
+import type { SignedRequestReplayResource, SignedRequestReplayStore } from './types.js'
 
-const timeKey = BED255_TIME_HEADER.toLocaleLowerCase()
-const nonceKey = BED255_NONCE_HEADER.toLocaleLowerCase()
-
-/**
- * Proper configuration:
- * - One needs to specify opts.cache as a redis resource that stores nonces for a while to
- * avoid requests duplication.
- */
 export const makeBasicEd25519Guard = (resource: string, opts?: BasicEd25519GuardOptions): BasicEd25519Guard => {
+  const memoryReplay = makeMemorySignedRequestReplayStore()
 
-  const cache = (context: Context) => context.hasResource(opts?.cache ?? BED255_CASHE_RESOURCE)
-    ? context.resource<Resource<ResourceRecord>>(opts?.cache ?? BED255_CASHE_RESOURCE)
-    : null
+  const replay = (context: Context): SignedRequestReplayStore => {
+    if (opts?.replay != null) {
+      return opts.replay
+    }
+    const alias = opts?.cache ?? BED255_CASHE_RESOURCE
+    if (context.hasResource(alias)) {
+      return makeResourceSignedRequestReplayStore(
+        context.resource<SignedRequestReplayResource>(alias)
+      )
+    }
+    return memoryReplay
+  }
 
   const guard: BasicEd25519Guard = createService<BasicEd25519Guard>(GUARD_ED25519, {
     authenticated: async req => {
@@ -78,39 +81,55 @@ export const makeBasicEd25519Guard = (resource: string, opts?: BasicEd25519Guard
         return { ...result, [key.toLowerCase()]: value }
       }, {} as { credential: string, signature: string })
 
+      if (typeof signature.credential !== 'string' || signature.credential.length === 0
+        || typeof signature.signature !== 'string' || signature.signature.length === 0) {
+        throw new AuthenPayloadError('signature')
+      }
+
       const trusted = await trust(context, resource, signature.credential, "id")
       if (trusted.user.credential == null) {
         return false as T
       }
 
+      const timestamp = req.headers?.[timeKey]
+      const nonce = req.headers?.[nonceKey]
+
       const payload = {
         body: req.body ?? {},
-        headers: { [timeKey]: req.headers[timeKey], [nonceKey]: req.headers[nonceKey] }
+        headers: { [timeKey]: timestamp, [nonceKey]: nonce }
       }
 
       if (!await trusted.key.verify(payload, signature.signature)) {
         return false as T
       }
 
-      if (typeof req.headers[timeKey] !== 'string') {
+      if (typeof timestamp !== 'string') {
         throw new AuthenPayloadError('timestamp')
       }
 
-      const createdAt = new Date(req.headers[timeKey])
+      const createdAt = new Date(timestamp)
+      const signedAt = createdAt.getTime()
+      if (!Number.isFinite(signedAt) || createdAt.toISOString() !== timestamp) {
+        throw new AuthenPayloadError('timestamp')
+      }
 
-      if (createdAt.getTime() + BED255_SIG_TTL < Date.now()) {
+      if (Math.abs(Date.now() - signedAt) > BED255_SIG_TTL) {
         throw new AuthenPayloadError('expired')
       }
 
-      const nonce = req.headers[nonceKey]
-      if (typeof nonce !== 'string') {
+      if (typeof nonce !== 'string' || nonce.length === 0) {
         throw new AuthenPayloadError('nonce')
       }
 
       try {
-        const tried = cache(context)
-        if (tried != null) {
-          await tried.create({ id: nonce }, { ttl: BED255_SIG_TTL / 1000 })
+        // The replay identity is the signing credential plus its nonce. A nonce used by one
+        // trusted service does not block another, while a captured request can be admitted once.
+        const claimed = await replay(context).claim(
+          `${signature.credential.length}:${signature.credential}${nonce}`,
+          new Date(signedAt + BED255_SIG_TTL)
+        )
+        if (!claimed) {
+          throw new AuthenPayloadError('nonce')
         }
       } catch {
         throw new AuthenPayloadError('nonce')
@@ -120,7 +139,7 @@ export const makeBasicEd25519Guard = (resource: string, opts?: BasicEd25519Guard
         token: authorization,
         userId: trusted.user.id,
         profileId: trusted.user.id,
-        entityId: trusted.user.entityId,
+        entitySlug: trusted.user.entitySlug,
         scopes: trusted.user.name != null ? [trusted.user.name] : [],
         type: AuthroizationType.Ed25519BasicSignature,
         source: context.cfg.service,

package/src/guards/basic-ed25519/types.ts

@@ -1,9 +1,26 @@
 import type { GuardService } from '@owlmeans/entrypoint'
+import type { ResourceRecord, WriteOptions } from '@owlmeans/resource'
+import type { BasicResource } from '@owlmeans/context'
 
 export interface BasicEd25519Guard extends GuardService {
 }
 
 export interface BasicEd25519GuardOptions {
+  /**
+   * Legacy resource alias. A Redis resource registered under this alias gives replay protection
+   * shared by every replica; when it is absent the guard falls back to its process-local store.
+   */
   cache?: string
+  /** Explicit replay store, for consumers that do not register a Resource on the context. */
+  replay?: SignedRequestReplayStore
 }
 
+/** A create-once claim over one signed request identity. */
+export interface SignedRequestReplayStore {
+  claim: (id: string, expiresAt: Date) => Promise<boolean>
+}
+
+/** The small Resource surface needed by the Redis-compatible replay adapter. */
+export interface SignedRequestReplayResource extends BasicResource {
+  create: (record: Partial<ResourceRecord>, opts?: WriteOptions) => Promise<ResourceRecord>
+}

package/src/index.ts

@@ -1,6 +1,9 @@
 export type * from './types.js'
+export type * from './entity/types.js'
 
-export * from './modules.js'
+export * from './schemas.js'
+export * from './entrypoints.js'
 export * from './consts.js'
+export * from './entity.js'
 export * from './middleware.js'
 export * from './guards/index.js'

package/src/middleware.ts

@@ -1,33 +1,33 @@
-import type { Middleware } from '@owlmeans/context'
-import { MiddlewareType, MiddlewareStage, AppType } from '@owlmeans/context'
-import { provideRequest } from '@owlmeans/client-entrypoint'
-import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
+import { type Middleware, MiddlewareType, MiddlewareStage, AppType } from '@owlmeans/context'
 import { AUTH_HEADER } from '@owlmeans/auth'
 import type { AbstractRequest, GuardService } from '@owlmeans/entrypoint'
+import type { Perked } from './types.local.js'
+import { clientRequestHelper } from '@owlmeans/client-entrypoint'
 
 export const authMiddleware: Middleware = {
   type: MiddlewareType.Context,
   stage: MiddlewareStage.Loading,
   apply: async context => {
     context.entrypoints<Perked>().forEach(module => {
-      if (module.route.route.type === AppType.Backend && module.call != null) {
-        const guards = module.getGuards()
-        if (guards.length > 0) {
+      if (module.route.route.type === AppType.Backend && module.invoke != null) {
+        if (module.getGuards().length > 0) {
           if (module._auth_common_middleware_applied === true) {
             return
           }
           module._auth_common_middleware_applied = true
-          // const auth = context.service<GuardService>(service)
-          const call = module.call
-          module.call = async (req, res) => {
+          // Wrapping `invoke` covers `call` too: `call` reads `invoke` off the entrypoint at the
+          // moment it runs, so both verbs carry the authentication header.
+          const invoke = module.invoke
+          module.invoke = (async req => {
             // @TODO Actually we may use multiple authentication headers with the same name
             // As I learnt its not always the case
-            const [token] = (await Promise.all(guards.map(
+            // Asked per call, not captured: an ancestor may have gained a guard since the
+            // middleware wrapped this entrypoint.
+            const [token] = (await Promise.all(module.getGuards().map(
               guard => context.service<GuardService>(guard).authenticated(req)
             ))).filter(token => token != null).reverse()
             if (token != null) {
-              await module.resolve()
-              const _req: Partial<AbstractRequest> = req ?? provideRequest(module.getAlias(), module.getPath())
+              const _req: Partial<AbstractRequest> = req ?? clientRequestHelper.provideRequest(module.alias, module.path())
               const headers = (_req.headers ?? {}) as Record<string, string | undefined>
               if (headers[AUTH_HEADER] == null) {
                 headers[AUTH_HEADER] = token
@@ -36,8 +36,8 @@ export const authMiddleware: Middleware = {
               }
             }
 
-            return call(req, res)
-          }
+            return invoke(req)
+          }) as typeof module.invoke
 
         }
       }
@@ -45,6 +45,3 @@ export const authMiddleware: Middleware = {
   }
 }
 
-interface Perked extends ClientEntrypoint<unknown> {
-  _auth_common_middleware_applied?: boolean
-}

package/src/schemas.ts

@@ -0,0 +1,12 @@
+import type { JSONSchemaType } from 'ajv'
+import type { SurrogateQuery } from './types.js'
+
+export const SurrogateQuerySchema: JSONSchemaType<SurrogateQuery> = {
+  type: 'object',
+  properties: {
+    intent: { type: 'string', maxLength: 32, nullable: true },
+    next: { type: 'string', maxLength: 2048, nullable: true },
+    method: { type: 'string', maxLength: 128, nullable: true },
+  },
+  additionalProperties: true,
+}

package/src/types.local.ts

@@ -0,0 +1,5 @@
+import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
+
+export interface Perked extends ClientEntrypoint<unknown> {
+  _auth_common_middleware_applied?: boolean
+}