@occupop/lib-auth 4.1.0 → 4.2.0

package/README.md

@@ -188,3 +188,35 @@ const response = await fetch(gatewayUrl, {
 - The token is identical to the one `@occupop/lib-context` 2.0.1's `makeGetAuthUserToken`
   produces for the same user, secret and time. `src/index_test.ts` checks this against tokens
   recorded from lib-context (`src/auth-user-token-vectors.json`).
+
+## Signing a scoped link
+
+`signScopedUserToken(scopedUser, jwtid)` signs a **scope** — a grant over named entities and fields,
+rather than a user — with `jwtid` as the token's `jti`, for a link a service hands out: an approval
+link, a one-entity grant.
+
+```typescript
+import { signScopedUserToken } from '@occupop/lib-auth'
+
+const scope = { [jobUuid]: { allowedFields: ['signOffWorkflow', 'userAssignments'] } }
+const token = signScopedUserToken(scope, approverUuid) // a string; throws for a null scope
+const link = `${appUrl}/sign-off/${token}`
+```
+
+`getScopedUser` reads such a token back, and `getAuthUser` returns `null` for it, so the two readers
+stay disjoint.
+
+- HS256 with `JWT_SECRET`, read when the function is called. If it is not set, the function throws
+  `'Env var JWT_SECRET not set?'`, as verification does.
+- `jwtid` becomes the token's `jti` claim. Callers commonly use the uuid of the row the link grants
+  access to, so a link can be traced back to it.
+- The payload is signed as given: no expiry, issuer or audience is added, and jsonwebtoken adds `iat`
+  only when the payload has none — a payload that already carries one keeps it.
+- **It throws `'scope not defined'` for a null scope**, where `signAuthUserToken` returns `null` for a
+  null user. That difference is deliberate, not an oversight: a caller minting a link has no use for a
+  null token.
+- Passing an `AuthUser` does not compile. The parameter is `ScopedUser | null`, and an `AuthUser`'s
+  `userUuid: string` conflicts with `ScopedUser`'s `userUuid?: undefined`.
+- The token is identical to the one `@occupop/lib-context` 2.0.1's `makeGetScopedUserToken` produces
+  for the same scope, `jti`, secret and time. `src/index_test.ts` checks this against recorded tokens
+  (`src/scoped-user-token-vectors.json`).

package/dist/index.d.ts

@@ -8,9 +8,24 @@ export type AuthUser = {
     readonly hiringCompanyUuid?: string;
     readonly recruitmentAgencyUuid?: string;
     readonly sysAdmin?: boolean;
+    readonly sysAdminEmail?: string;
     readonly isAdmin?: boolean;
     readonly isSuperAdmin?: boolean;
+    readonly permissions?: Permission;
 };
+export interface Permission {
+    isSuperAdmin: boolean;
+    isAdmin: boolean;
+    candidates: boolean;
+    favorites: boolean;
+    recruiters: boolean;
+    formsDocuments: boolean;
+    contracts: boolean;
+    jobRequisition: boolean;
+    jobRequisitionCreate: boolean;
+    jobsCreate: boolean;
+    jobsPublish: boolean;
+}
 export type ScopedUser = {
     readonly userUuid?: undefined;
     readonly [entityUuid: string]: {
@@ -26,6 +41,15 @@ export declare function getScopedUser(req: Request): ScopedUser | null;
  * `@occupop/lib-context` 2.0.1's `makeGetAuthUserToken` produces. Returns `null` for no user.
  */
 export declare function signAuthUserToken(authUser: AuthUser | null): string | null;
+/**
+ * Signs `scopedUser` with `JWT_SECRET` (HS256) and `jwtid` as the token's `jti`, for a scoped link
+ * a service hands out — an approval link, a one-entity grant. The payload is signed as given: no
+ * expiry, issuer or audience is added, and jsonwebtoken adds `iat` when the payload has none. The
+ * token is the one `@occupop/lib-context` 2.0.1's `makeGetScopedUserToken` produces. Throws for an
+ * absent scope — unlike `signAuthUserToken`, which returns `null` for an absent user, because a
+ * caller minting a link has no meaningful use for a null token.
+ */
+export declare function signScopedUserToken(scopedUser: ScopedUser | null, jwtid: string): string;
 export declare function makeAuthContextValueFunction<IContainer extends AwilixContainer>({ container }: {
     container: IContainer;
 }): ({ req }: {

package/dist/index.js

@@ -44,6 +44,21 @@ export function signAuthUserToken(authUser) {
         throw 'Env var JWT_SECRET not set?';
     return jwt.sign(authUser, process.env.JWT_SECRET);
 }
+/**
+ * Signs `scopedUser` with `JWT_SECRET` (HS256) and `jwtid` as the token's `jti`, for a scoped link
+ * a service hands out — an approval link, a one-entity grant. The payload is signed as given: no
+ * expiry, issuer or audience is added, and jsonwebtoken adds `iat` when the payload has none. The
+ * token is the one `@occupop/lib-context` 2.0.1's `makeGetScopedUserToken` produces. Throws for an
+ * absent scope — unlike `signAuthUserToken`, which returns `null` for an absent user, because a
+ * caller minting a link has no meaningful use for a null token.
+ */
+export function signScopedUserToken(scopedUser, jwtid) {
+    if (!scopedUser)
+        throw new Error('scope not defined');
+    if (!process.env.JWT_SECRET)
+        throw 'Env var JWT_SECRET not set?';
+    return jwt.sign(scopedUser, process.env.JWT_SECRET, { jwtid });
+}
 export function makeAuthContextValueFunction({ container }) {
     return async ({ req }) => {
         const authUser = getAuthUser(req);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@occupop/lib-auth",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "main": "dist/index.js",
   "module": "index.ts",
   "description": "...",