@grantjs/schema 1.20.2 → 1.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grantjs/schema",
-  "version": "1.20.2",
+  "version": "1.22.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/generated/graphql.ts

@@ -1316,7 +1316,16 @@ export type ExportProjectUserCredentialsQueryVariables = Exact<{
 
 export type ExportProjectUserCredentialsQuery = {
   exportProjectUserCredentials: {
-    users: Array<{ userId: string; password: { algorithm: string; hash: string } | null }>;
+    users: Array<{
+      userId: string;
+      password: { algorithm: string; hash: string } | null;
+      apiKeySecrets: Array<{
+        apiKeyId: string;
+        clientId: string;
+        fingerprint: string | null;
+        secret: string | null;
+      }> | null;
+    }>;
   };
 };
 
@@ -1491,6 +1500,7 @@ export type ProjectSyncJobQuery = {
       passwordsUpdated: number;
       passwordsUnchanged: number;
       passwordsSkippedExisting: number;
+      usersSkippedTombstoned: number;
       warnings: Array<string>;
     } | null;
   };
@@ -1547,6 +1557,18 @@ export type RequestProjectSyncUploadUrlMutation = {
   };
 };
 
+export type SetProjectExportableApiKeySecretsMutationVariables = Exact<{
+  input: Types.SetProjectExportableApiKeySecretsInput;
+}>;
+
+export type SetProjectExportableApiKeySecretsMutation = {
+  setProjectExportableApiKeySecrets: {
+    id: string;
+    exportableApiKeySecrets: boolean;
+    updatedAt: Date;
+  };
+};
+
 export type StartProjectExportMutationVariables = Exact<{
   id: string | number;
   scope: Types.Scope;
@@ -7545,6 +7567,19 @@ export const ExportProjectUserCredentialsDocument = {
                           ],
                         },
                       },
+                      {
+                        kind: 'Field',
+                        name: { kind: 'Name', value: 'apiKeySecrets' },
+                        selectionSet: {
+                          kind: 'SelectionSet',
+                          selections: [
+                            { kind: 'Field', name: { kind: 'Name', value: 'apiKeyId' } },
+                            { kind: 'Field', name: { kind: 'Name', value: 'clientId' } },
+                            { kind: 'Field', name: { kind: 'Name', value: 'fingerprint' } },
+                            { kind: 'Field', name: { kind: 'Name', value: 'secret' } },
+                          ],
+                        },
+                      },
                     ],
                   },
                 },
@@ -8165,6 +8200,7 @@ export const ProjectSyncJobDocument = {
                       { kind: 'Field', name: { kind: 'Name', value: 'passwordsUpdated' } },
                       { kind: 'Field', name: { kind: 'Name', value: 'passwordsUnchanged' } },
                       { kind: 'Field', name: { kind: 'Name', value: 'passwordsSkippedExisting' } },
+                      { kind: 'Field', name: { kind: 'Name', value: 'usersSkippedTombstoned' } },
                       { kind: 'Field', name: { kind: 'Name', value: 'warnings' } },
                     ],
                   },
@@ -8405,6 +8441,56 @@ export const RequestProjectSyncUploadUrlDocument = {
   RequestProjectSyncUploadUrlMutation,
   RequestProjectSyncUploadUrlMutationVariables
 >;
+export const SetProjectExportableApiKeySecretsDocument = {
+  kind: 'Document',
+  definitions: [
+    {
+      kind: 'OperationDefinition',
+      operation: 'mutation',
+      name: { kind: 'Name', value: 'SetProjectExportableApiKeySecrets' },
+      variableDefinitions: [
+        {
+          kind: 'VariableDefinition',
+          variable: { kind: 'Variable', name: { kind: 'Name', value: 'input' } },
+          type: {
+            kind: 'NonNullType',
+            type: {
+              kind: 'NamedType',
+              name: { kind: 'Name', value: 'SetProjectExportableApiKeySecretsInput' },
+            },
+          },
+        },
+      ],
+      selectionSet: {
+        kind: 'SelectionSet',
+        selections: [
+          {
+            kind: 'Field',
+            name: { kind: 'Name', value: 'setProjectExportableApiKeySecrets' },
+            arguments: [
+              {
+                kind: 'Argument',
+                name: { kind: 'Name', value: 'input' },
+                value: { kind: 'Variable', name: { kind: 'Name', value: 'input' } },
+              },
+            ],
+            selectionSet: {
+              kind: 'SelectionSet',
+              selections: [
+                { kind: 'Field', name: { kind: 'Name', value: 'id' } },
+                { kind: 'Field', name: { kind: 'Name', value: 'exportableApiKeySecrets' } },
+                { kind: 'Field', name: { kind: 'Name', value: 'updatedAt' } },
+              ],
+            },
+          },
+        ],
+      },
+    },
+  ],
+} as unknown as DocumentNode<
+  SetProjectExportableApiKeySecretsMutation,
+  SetProjectExportableApiKeySecretsMutationVariables
+>;
 export const StartProjectExportDocument = {
   kind: 'Document',
   definitions: [

package/src/generated/resolvers.ts

@@ -283,6 +283,7 @@ export type ResolversTypes = ResolversObject<{
   ExchangeApiKeyInput: Types.ExchangeApiKeyInput;
   ExchangeApiKeyResult: ResolverTypeWrapper<Types.ExchangeApiKeyResult>;
   ExportProjectUserCredentialsInput: Types.ExportProjectUserCredentialsInput;
+  ExportedApiKeySecret: ResolverTypeWrapper<Types.ExportedApiKeySecret>;
   ExportedPasswordCredential: ResolverTypeWrapper<Types.ExportedPasswordCredential>;
   ExportedProjectUserCredential: ResolverTypeWrapper<Types.ExportedProjectUserCredential>;
   GenerateMyMfaRecoveryCodesInput: Types.GenerateMyMfaRecoveryCodesInput;
@@ -389,6 +390,7 @@ export type ResolversTypes = ResolversObject<{
   ProjectTag: ResolverTypeWrapper<Types.ProjectTag>;
   ProjectUser: ResolverTypeWrapper<Types.ProjectUser>;
   ProjectUserApiKey: ResolverTypeWrapper<Types.ProjectUserApiKey>;
+  ProjectUserApiKeyCredential: ResolverTypeWrapper<Types.ProjectUserApiKeyCredential>;
   ProjectUserCredentialExport: ResolverTypeWrapper<Types.ProjectUserCredentialExport>;
   ProjectUserGroup: ResolverTypeWrapper<Types.ProjectUserGroup>;
   ProjectUserPasswordCredential: ResolverTypeWrapper<Types.ProjectUserPasswordCredential>;
@@ -507,6 +509,7 @@ export type ResolversTypes = ResolversObject<{
   SessionExportData: ResolverTypeWrapper<Types.SessionExportData>;
   SetMyNotificationPreferenceInput: Types.SetMyNotificationPreferenceInput;
   SetMyPrimaryMfaDeviceInput: Types.SetMyPrimaryMfaDeviceInput;
+  SetProjectExportableApiKeySecretsInput: Types.SetProjectExportableApiKeySecretsInput;
   SetProjectUserEmailInput: Types.SetProjectUserEmailInput;
   SetProjectUserPasswordInput: Types.SetProjectUserPasswordInput;
   SigningKey: ResolverTypeWrapper<Types.SigningKey>;
@@ -700,6 +703,7 @@ export type ResolversParentTypes = ResolversObject<{
   ExchangeApiKeyInput: Types.ExchangeApiKeyInput;
   ExchangeApiKeyResult: Types.ExchangeApiKeyResult;
   ExportProjectUserCredentialsInput: Types.ExportProjectUserCredentialsInput;
+  ExportedApiKeySecret: Types.ExportedApiKeySecret;
   ExportedPasswordCredential: Types.ExportedPasswordCredential;
   ExportedProjectUserCredential: Types.ExportedProjectUserCredential;
   GenerateMyMfaRecoveryCodesInput: Types.GenerateMyMfaRecoveryCodesInput;
@@ -782,6 +786,7 @@ export type ResolversParentTypes = ResolversObject<{
   ProjectTag: Types.ProjectTag;
   ProjectUser: Types.ProjectUser;
   ProjectUserApiKey: Types.ProjectUserApiKey;
+  ProjectUserApiKeyCredential: Types.ProjectUserApiKeyCredential;
   ProjectUserCredentialExport: Types.ProjectUserCredentialExport;
   ProjectUserGroup: Types.ProjectUserGroup;
   ProjectUserPasswordCredential: Types.ProjectUserPasswordCredential;
@@ -896,6 +901,7 @@ export type ResolversParentTypes = ResolversObject<{
   SessionExportData: Types.SessionExportData;
   SetMyNotificationPreferenceInput: Types.SetMyNotificationPreferenceInput;
   SetMyPrimaryMfaDeviceInput: Types.SetMyPrimaryMfaDeviceInput;
+  SetProjectExportableApiKeySecretsInput: Types.SetProjectExportableApiKeySecretsInput;
   SetProjectUserEmailInput: Types.SetProjectUserEmailInput;
   SetProjectUserPasswordInput: Types.SetProjectUserPasswordInput;
   SigningKey: Types.SigningKey;
@@ -1338,6 +1344,17 @@ export type ExchangeApiKeyResultResolvers<
   expiresIn?: Resolver<ResolversTypes['Int'], ParentType, ContextType>;
 }>;
 
+export type ExportedApiKeySecretResolvers<
+  ContextType = any,
+  ParentType extends ResolversParentTypes['ExportedApiKeySecret'] =
+    ResolversParentTypes['ExportedApiKeySecret'],
+> = ResolversObject<{
+  apiKeyId?: Resolver<ResolversTypes['ID'], ParentType, ContextType>;
+  clientId?: Resolver<ResolversTypes['String'], ParentType, ContextType>;
+  fingerprint?: Resolver<Types.Maybe<ResolversTypes['String']>, ParentType, ContextType>;
+  secret?: Resolver<Types.Maybe<ResolversTypes['String']>, ParentType, ContextType>;
+}>;
+
 export type ExportedPasswordCredentialResolvers<
   ContextType = any,
   ParentType extends ResolversParentTypes['ExportedPasswordCredential'] =
@@ -1352,6 +1369,11 @@ export type ExportedProjectUserCredentialResolvers<
   ParentType extends ResolversParentTypes['ExportedProjectUserCredential'] =
     ResolversParentTypes['ExportedProjectUserCredential'],
 > = ResolversObject<{
+  apiKeySecrets?: Resolver<
+    Types.Maybe<Array<ResolversTypes['ExportedApiKeySecret']>>,
+    ParentType,
+    ContextType
+  >;
   password?: Resolver<
     Types.Maybe<ResolversTypes['ExportedPasswordCredential']>,
     ParentType,
@@ -1997,6 +2019,12 @@ export type MutationResolvers<
     ContextType,
     RequireFields<Types.MutationSetMyPrimaryMfaDeviceArgs, 'input'>
   >;
+  setProjectExportableApiKeySecrets?: Resolver<
+    ResolversTypes['Project'],
+    ParentType,
+    ContextType,
+    RequireFields<Types.MutationSetProjectExportableApiKeySecretsArgs, 'input'>
+  >;
   setProjectUserEmail?: Resolver<
     ResolversTypes['User'],
     ParentType,
@@ -2577,6 +2605,7 @@ export type ProjectResolvers<
   createdAt?: Resolver<ResolversTypes['Date'], ParentType, ContextType>;
   deletedAt?: Resolver<Types.Maybe<ResolversTypes['Date']>, ParentType, ContextType>;
   description?: Resolver<Types.Maybe<ResolversTypes['String']>, ParentType, ContextType>;
+  exportableApiKeySecrets?: Resolver<ResolversTypes['Boolean'], ParentType, ContextType>;
   groups?: Resolver<Types.Maybe<Array<ResolversTypes['Group']>>, ParentType, ContextType>;
   id?: Resolver<ResolversTypes['ID'], ParentType, ContextType>;
   name?: Resolver<ResolversTypes['String'], ParentType, ContextType>;
@@ -2887,6 +2916,18 @@ export type ProjectUserApiKeyResolvers<
   __isTypeOf?: IsTypeOfResolverFn<ParentType, ContextType>;
 }>;
 
+export type ProjectUserApiKeyCredentialResolvers<
+  ContextType = any,
+  ParentType extends ResolversParentTypes['ProjectUserApiKeyCredential'] =
+    ResolversParentTypes['ProjectUserApiKeyCredential'],
+> = ResolversObject<{
+  apiKeyId?: Resolver<ResolversTypes['ID'], ParentType, ContextType>;
+  clientId?: Resolver<ResolversTypes['String'], ParentType, ContextType>;
+  exportable?: Resolver<ResolversTypes['Boolean'], ParentType, ContextType>;
+  fingerprint?: Resolver<Types.Maybe<ResolversTypes['String']>, ParentType, ContextType>;
+  updatedAt?: Resolver<ResolversTypes['Date'], ParentType, ContextType>;
+}>;
+
 export type ProjectUserCredentialExportResolvers<
   ContextType = any,
   ParentType extends ResolversParentTypes['ProjectUserCredentialExport'] =
@@ -3404,6 +3445,7 @@ export type SyncProjectResultResolvers<
   userRolesAssigned?: Resolver<ResolversTypes['Int'], ParentType, ContextType>;
   userTagsLinked?: Resolver<ResolversTypes['Int'], ParentType, ContextType>;
   usersCreated?: Resolver<ResolversTypes['Int'], ParentType, ContextType>;
+  usersSkippedTombstoned?: Resolver<ResolversTypes['Int'], ParentType, ContextType>;
   warnings?: Resolver<Array<ResolversTypes['String']>, ParentType, ContextType>;
 }>;
 
@@ -3500,6 +3542,11 @@ export type UserResolvers<
   ParentType extends ResolversParentTypes['User'] = ResolversParentTypes['User'],
 > = ResolversObject<{
   accounts?: Resolver<Types.Maybe<Array<ResolversTypes['Account']>>, ParentType, ContextType>;
+  apiKeyCredentials?: Resolver<
+    Types.Maybe<Array<ResolversTypes['ProjectUserApiKeyCredential']>>,
+    ParentType,
+    ContextType
+  >;
   authenticationMethods?: Resolver<
     Types.Maybe<Array<ResolversTypes['UserAuthenticationMethod']>>,
     ParentType,
@@ -3836,6 +3883,7 @@ export type Resolvers<ContextType = any> = ResolversObject<{
   CredentialExportData?: CredentialExportDataResolvers<ContextType>;
   Date?: GraphQLScalarType;
   ExchangeApiKeyResult?: ExchangeApiKeyResultResolvers<ContextType>;
+  ExportedApiKeySecret?: ExportedApiKeySecretResolvers<ContextType>;
   ExportedPasswordCredential?: ExportedPasswordCredentialResolvers<ContextType>;
   ExportedProjectUserCredential?: ExportedProjectUserCredentialResolvers<ContextType>;
   Group?: GroupResolvers<ContextType>;
@@ -3896,6 +3944,7 @@ export type Resolvers<ContextType = any> = ResolversObject<{
   ProjectTag?: ProjectTagResolvers<ContextType>;
   ProjectUser?: ProjectUserResolvers<ContextType>;
   ProjectUserApiKey?: ProjectUserApiKeyResolvers<ContextType>;
+  ProjectUserApiKeyCredential?: ProjectUserApiKeyCredentialResolvers<ContextType>;
   ProjectUserCredentialExport?: ProjectUserCredentialExportResolvers<ContextType>;
   ProjectUserGroup?: ProjectUserGroupResolvers<ContextType>;
   ProjectUserPasswordCredential?: ProjectUserPasswordCredentialResolvers<ContextType>;

package/src/generated/schema-types.ts

@@ -453,6 +453,11 @@ export type CdmKeyResolverInput = {
    * import/export.
    */
   findBy?: InputMaybe<CdmFindBy>;
+  /**
+   * Only with `findBy: key`: an existing, live Grant user this key is, reused instead of creating one and marked
+   * with the key for this project. Refused for a missing, deleted or already-imported-under-another-key user.
+   */
+  grantUserId?: InputMaybe<Scalars['ID']['input']>;
   ifMissing?: InputMaybe<CdmIfMissing>;
   /**
    * Identifier value. For `findBy: email`, Grant normalizes this to lowercase
@@ -813,6 +818,11 @@ export type CredentialExportData = {
  * not as a second export.
  */
 export enum CredentialKind {
+  /**
+   * The API keys of the project user, with the plaintext secret of each key the project keeps an
+   * exportable copy of (a project that opted in to exportable API-key secrets).
+   */
+  ApiKeySecret = 'API_KEY_SECRET',
   /** The project password credential (bcrypt hash). */
   Password = 'PASSWORD',
 }
@@ -871,6 +881,26 @@ export type ExportProjectUserCredentialsInput = {
   userIds: Array<Scalars['ID']['input']>;
 };
 
+/** One API key of a project user in an export. `secret` is a credential: handle it like one. */
+export type ExportedApiKeySecret = {
+  __typename?: 'ExportedApiKeySecret';
+  apiKeyId: Scalars['ID']['output'];
+  /** The key's public client id. */
+  clientId: Scalars['String']['output'];
+  /**
+   * Lowercase hex SHA-256 of the secret string as issued, to compare with `sha256(secret)` of the
+   * value a receiver holds. `null` for a key created before the fingerprint existed and not rotated
+   * since.
+   */
+  fingerprint?: Maybe<Scalars['String']['output']>;
+  /**
+   * The plaintext secret: 88 characters, standard base64 of 64 random bytes. `null` for a key the
+   * project holds no copy of (created before the project opted in, created by a CDM import, or
+   * rotated by a CDM replace): Grant cannot recover it.
+   */
+  secret?: Maybe<Scalars['String']['output']>;
+};
+
 /** A stored password hash in CDM shape. Secret-equivalent: handle like a credential. */
 export type ExportedPasswordCredential = {
   __typename?: 'ExportedPasswordCredential';
@@ -882,7 +912,12 @@ export type ExportedPasswordCredential = {
 
 export type ExportedProjectUserCredential = {
   __typename?: 'ExportedProjectUserCredential';
-  /** `null` when the member has no project password credential. */
+  /**
+   * The member's live (not revoked, not deleted) project-user API keys, oldest first. `null` when the
+   * `API_KEY_SECRET` kind was not requested; `[]` for a member with no key.
+   */
+  apiKeySecrets?: Maybe<Array<ExportedApiKeySecret>>;
+  /** `null` when the member has no project password credential, and when the `PASSWORD` kind was not requested. */
   password?: Maybe<ExportedPasswordCredential>;
   userId: Scalars['ID']['output'];
 };
@@ -1324,6 +1359,15 @@ export type Mutation = {
   setMyNotificationPreference: NotificationPreference;
   setMyPrimaryAuthenticationMethod: UserAuthenticationMethod;
   setMyPrimaryMfaDevice: MfaDevice;
+  /**
+   * Opt a project in or out of keeping an exportable, encrypted copy of a project user's API-key
+   * secret. Project scopes only. Requires `Project:SetExportableApiKeySecrets`, held by the Owner and
+   * Admin roles and not by Dev. Enabling fails with a configuration error while
+   * `API_KEY_EXPORTABLE_SECRET_ENCRYPTION_KEY` is not set; disabling never needs it. Each change is
+   * audited on the project with the old and new value; the same value is a no-op. Nothing is
+   * back-filled: keys that exist before the opt-in keep only their hash.
+   */
+  setProjectExportableApiKeySecrets: Project;
   /**
    * Set or replace a project member's Email authentication method as unverified.
    * `project.user_email_changed` carries ids only, never the address.
@@ -1699,6 +1743,10 @@ export type MutationSetMyPrimaryMfaDeviceArgs = {
   input: SetMyPrimaryMfaDeviceInput;
 };
 
+export type MutationSetProjectExportableApiKeySecretsArgs = {
+  input: SetProjectExportableApiKeySecretsInput;
+};
+
 export type MutationSetProjectUserEmailArgs = {
   input: SetProjectUserEmailInput;
 };
@@ -2236,6 +2284,13 @@ export type Project = Auditable & {
   createdAt: Scalars['Date']['output'];
   deletedAt?: Maybe<Scalars['Date']['output']>;
   description?: Maybe<Scalars['String']['output']>;
+  /**
+   * Whether this project keeps an exportable, encrypted copy of a project user's API-key secret at
+   * create and rotate. Off by default; set with `setProjectExportableApiKeySecrets`. A plain
+   * configuration flag: it says nothing about any key, and nothing is back-filled for keys that
+   * already exist.
+   */
+  exportableApiKeySecrets: Scalars['Boolean']['output'];
   groups?: Maybe<Array<Group>>;
   id: Scalars['ID']['output'];
   name: Scalars['String']['output'];
@@ -2580,7 +2635,33 @@ export type ProjectUserApiKey = Auditable & {
   userId: Scalars['ID']['output'];
 };
 
-/** Result of `exportProjectUserCredentials`. This is the one place a credential hash leaves Grant. */
+/**
+ * Non-secret facts about one of a project user's API keys. Never contains the secret, the hash or the
+ * encrypted copy.
+ */
+export type ProjectUserApiKeyCredential = {
+  __typename?: 'ProjectUserApiKeyCredential';
+  apiKeyId: Scalars['ID']['output'];
+  /** The key's public client id. */
+  clientId: Scalars['String']['output'];
+  /** An encrypted copy of the key's current secret exists (only in a project that opted in). */
+  exportable: Scalars['Boolean']['output'];
+  /**
+   * Lowercase hex SHA-256 of the secret string as issued (the text the client received, never the
+   * stored hash): a change detector a holder of the secret can compare against. `null` for a key
+   * created before this field existed and not rotated since. Grant issues secrets of 32 or 64 random
+   * bytes, so the digest cannot be guessed offline; a secret chosen by an importer is only as strong
+   * as the importer made it.
+   */
+  fingerprint?: Maybe<Scalars['String']['output']>;
+  /** When the key last changed (created, rotated or edited). */
+  updatedAt: Scalars['Date']['output'];
+};
+
+/**
+ * Result of `exportProjectUserCredentials`. This is the one place a credential hash, and the plaintext
+ * secret of an exportable API key, leaves Grant.
+ */
 export type ProjectUserCredentialExport = {
   __typename?: 'ProjectUserCredentialExport';
   users: Array<ExportedProjectUserCredential>;
@@ -2629,11 +2710,14 @@ export type Query = {
   /** Public signup policy. No authentication required. */
   authSignupPolicy: AuthSignupPolicy;
   /**
-   * Export project members' password hashes in CDM shape, for a downstream identity mirror.
-   * This is the one audited exception to "APIs expose only whether a password exists": it
-   * requires `ProjectUser:ExportCredentials` (held by no standard group), every call is audited,
-   * and it returns hashes. Any non-member in `userIds` fails the whole call; members without a
-   * project credential are listed with `password: null`.
+   * Export project members' credentials for a downstream identity mirror: password hashes in CDM
+   * shape (`PASSWORD`) and the plaintext secrets of their API keys (`API_KEY_SECRET`, only for keys
+   * of a project that opted in to exportable API-key secrets). This is the one audited exception to
+   * "APIs expose only whether a password exists" and to "an API-key secret is shown once": it
+   * requires `ProjectUser:ExportCredentials` (held by no standard group), every call is audited
+   * (one summary row, plus one row per exported API-key secret), and it returns credentials. Any
+   * non-member in `userIds` fails the whole call; members without a project credential are listed
+   * with `password: null`, and a key without a copy with `secret: null`.
    */
   exportProjectUserCredentials: ProjectUserCredentialExport;
   groups: GroupPage;
@@ -3633,6 +3717,19 @@ export type SetMyPrimaryMfaDeviceInput = {
   factorId: Scalars['ID']['input'];
 };
 
+export type SetProjectExportableApiKeySecretsInput = {
+  /**
+   * `true` opts the project in; `false` opts it out and deletes every exportable copy the project
+   * holds. Setting the value the project already has changes nothing and is not audited.
+   */
+  enabled: Scalars['Boolean']['input'];
+  /**
+   * The project to change, as the scope the request is authorized in: `accountProject` or
+   * `organizationProject` only.
+   */
+  scope: Scope;
+};
+
 export type SetProjectUserEmailInput = {
   /**
    * Unverified Email authentication method. Project-scope only.
@@ -3797,6 +3894,11 @@ export type SyncProjectResult = {
   userRolesAssigned: Scalars['Int']['output'];
   userTagsLinked: Scalars['Int']['output'];
   usersCreated: Scalars['Int']['output'];
+  /**
+   * Document users not created because the person deleted this imported identity; their
+   * membership, credential and API keys were not written either.
+   */
+  usersSkippedTombstoned: Scalars['Int']['output'];
   warnings: Array<Scalars['String']['output']>;
 };
 
@@ -4217,6 +4319,13 @@ export type UpsertProjectOAuthConnectionInput = {
 export type User = Auditable & {
   __typename?: 'User';
   accounts?: Maybe<Array<Account>>;
+  /**
+   * Non-secret facts about the user's live (not revoked, not deleted) project-user API keys in the
+   * request's project scope, oldest first. `null` outside a project scope or when the caller lacks
+   * `ProjectUser:ExportCredentials` (never an error); `[]` for a member with no key. The secret, the
+   * hash and the encrypted copy are never returned here.
+   */
+  apiKeyCredentials?: Maybe<Array<ProjectUserApiKeyCredential>>;
   authenticationMethods?: Maybe<Array<UserAuthenticationMethod>>;
   createdAt: Scalars['Date']['output'];
   deletedAt?: Maybe<Scalars['Date']['output']>;

package/src/operations/project-users/exportProjectUserCredentials.graphql

@@ -6,6 +6,12 @@ query ExportProjectUserCredentials($input: ExportProjectUserCredentialsInput!) {
         algorithm
         hash
       }
+      apiKeySecrets {
+        apiKeyId
+        clientId
+        fingerprint
+        secret
+      }
     }
   }
 }

package/src/operations/projects/project-sync-job.graphql

@@ -29,6 +29,7 @@ query ProjectSyncJob($id: ID!, $scope: Scope!, $jobId: ID!) {
       passwordsUpdated
       passwordsUnchanged
       passwordsSkippedExisting
+      usersSkippedTombstoned
       warnings
     }
     warnings

package/src/operations/projects/set-project-exportable-api-key-secrets.graphql

@@ -0,0 +1,7 @@
+mutation SetProjectExportableApiKeySecrets($input: SetProjectExportableApiKeySecretsInput!) {
+  setProjectExportableApiKeySecrets(input: $input) {
+    id
+    exportableApiKeySecrets
+    updatedAt
+  }
+}

package/src/schema/project-users/queries/export-project-user-credentials.graphql

@@ -1,10 +1,13 @@
 extend type Query {
   """
-  Export project members' password hashes in CDM shape, for a downstream identity mirror.
-  This is the one audited exception to "APIs expose only whether a password exists": it
-  requires `ProjectUser:ExportCredentials` (held by no standard group), every call is audited,
-  and it returns hashes. Any non-member in `userIds` fails the whole call; members without a
-  project credential are listed with `password: null`.
+  Export project members' credentials for a downstream identity mirror: password hashes in CDM
+  shape (`PASSWORD`) and the plaintext secrets of their API keys (`API_KEY_SECRET`, only for keys
+  of a project that opted in to exportable API-key secrets). This is the one audited exception to
+  "APIs expose only whether a password exists" and to "an API-key secret is shown once": it
+  requires `ProjectUser:ExportCredentials` (held by no standard group), every call is audited
+  (one summary row, plus one row per exported API-key secret), and it returns credentials. Any
+  non-member in `userIds` fails the whole call; members without a project credential are listed
+  with `password: null`, and a key without a copy with `secret: null`.
   """
   exportProjectUserCredentials(
     input: ExportProjectUserCredentialsInput!

package/src/schema/project-users/types/credential-kind.graphql

@@ -5,4 +5,9 @@ not as a second export.
 enum CredentialKind {
   "The project password credential (bcrypt hash)."
   PASSWORD
+  """
+  The API keys of the project user, with the plaintext secret of each key the project keeps an
+  exportable copy of (a project that opted in to exportable API-key secrets).
+  """
+  API_KEY_SECRET
 }

package/src/schema/project-users/types/project-user-api-key-credential.graphql

@@ -0,0 +1,21 @@
+"""
+Non-secret facts about one of a project user's API keys. Never contains the secret, the hash or the
+encrypted copy.
+"""
+type ProjectUserApiKeyCredential {
+  apiKeyId: ID!
+  "The key's public client id."
+  clientId: String!
+  """
+  Lowercase hex SHA-256 of the secret string as issued (the text the client received, never the
+  stored hash): a change detector a holder of the secret can compare against. `null` for a key
+  created before this field existed and not rotated since. Grant issues secrets of 32 or 64 random
+  bytes, so the digest cannot be guessed offline; a secret chosen by an importer is only as strong
+  as the importer made it.
+  """
+  fingerprint: String
+  "An encrypted copy of the key's current secret exists (only in a project that opted in)."
+  exportable: Boolean!
+  "When the key last changed (created, rotated or edited)."
+  updatedAt: Date!
+}

package/src/schema/project-users/types/project-user-credential-export.graphql

@@ -1,5 +1,6 @@
 """
-Result of `exportProjectUserCredentials`. This is the one place a credential hash leaves Grant.
+Result of `exportProjectUserCredentials`. This is the one place a credential hash, and the plaintext
+secret of an exportable API key, leaves Grant.
 """
 type ProjectUserCredentialExport {
   users: [ExportedProjectUserCredential!]!
@@ -7,8 +8,34 @@ type ProjectUserCredentialExport {
 
 type ExportedProjectUserCredential {
   userId: ID!
-  "`null` when the member has no project password credential."
+  "`null` when the member has no project password credential, and when the `PASSWORD` kind was not requested."
   password: ExportedPasswordCredential
+  """
+  The member's live (not revoked, not deleted) project-user API keys, oldest first. `null` when the
+  `API_KEY_SECRET` kind was not requested; `[]` for a member with no key.
+  """
+  apiKeySecrets: [ExportedApiKeySecret!]
+}
+
+"""
+One API key of a project user in an export. `secret` is a credential: handle it like one.
+"""
+type ExportedApiKeySecret {
+  apiKeyId: ID!
+  "The key's public client id."
+  clientId: String!
+  """
+  Lowercase hex SHA-256 of the secret string as issued, to compare with `sha256(secret)` of the
+  value a receiver holds. `null` for a key created before the fingerprint existed and not rotated
+  since.
+  """
+  fingerprint: String
+  """
+  The plaintext secret: 88 characters, standard base64 of 64 random bytes. `null` for a key the
+  project holds no copy of (created before the project opted in, created by a CDM import, or
+  rotated by a CDM replace): Grant cannot recover it.
+  """
+  secret: String
 }
 
 """

package/src/schema/projects/inputs/set-project-exportable-api-key-secrets.graphql

@@ -0,0 +1,12 @@
+input SetProjectExportableApiKeySecretsInput {
+  """
+  The project to change, as the scope the request is authorized in: `accountProject` or
+  `organizationProject` only.
+  """
+  scope: Scope!
+  """
+  `true` opts the project in; `false` opts it out and deletes every exportable copy the project
+  holds. Setting the value the project already has changes nothing and is not audited.
+  """
+  enabled: Boolean!
+}

package/src/schema/projects/inputs/sync-project-cdm.graphql

@@ -53,6 +53,11 @@ input CdmKeyResolverInput {
   """
   findBy: CdmFindBy
   ifMissing: CdmIfMissing
+  """
+  Only with `findBy: key`: an existing, live Grant user this key is, reused instead of creating one and marked
+  with the key for this project. Refused for a missing, deleted or already-imported-under-another-key user.
+  """
+  grantUserId: ID
 }
 
 """

package/src/schema/projects/mutations/set-project-exportable-api-key-secrets.graphql

@@ -0,0 +1,11 @@
+extend type Mutation {
+  """
+  Opt a project in or out of keeping an exportable, encrypted copy of a project user's API-key
+  secret. Project scopes only. Requires `Project:SetExportableApiKeySecrets`, held by the Owner and
+  Admin roles and not by Dev. Enabling fails with a configuration error while
+  `API_KEY_EXPORTABLE_SECRET_ENCRYPTION_KEY` is not set; disabling never needs it. Each change is
+  audited on the project with the old and new value; the same value is a no-op. Nothing is
+  back-filled: keys that exist before the opt-in keep only their hash.
+  """
+  setProjectExportableApiKeySecrets(input: SetProjectExportableApiKeySecretsInput!): Project!
+}

package/src/schema/projects/types/project.graphql

@@ -12,6 +12,13 @@ type Project implements Auditable {
   Whether the OAuth help panel is shown. Null uses Grant's default (shown).
   """
   showHelpPanel: Boolean
+  """
+  Whether this project keeps an exportable, encrypted copy of a project user's API-key secret at
+  create and rotate. Off by default; set with `setProjectExportableApiKeySecrets`. A plain
+  configuration flag: it says nothing about any key, and nothing is back-filled for keys that
+  already exist.
+  """
+  exportableApiKeySecrets: Boolean!
   roles: [Role!]
   groups: [Group!]
   permissions: [Permission!]

package/src/schema/projects/types/sync-project-result.graphql

@@ -51,6 +51,11 @@ type SyncProjectResult {
   reset in Grant, not imported.
   """
   passwordsSkippedExisting: Int!
+  """
+  Document users not created because the person deleted this imported identity; their
+  membership, credential and API keys were not written either.
+  """
+  usersSkippedTombstoned: Int!
   resourcesCreated: Int!
   permissionsCreated: Int!
   tagsCreated: Int!

package/src/schema/users/types/user.graphql

@@ -21,6 +21,13 @@ type User implements Auditable {
   stored hash string: a change detector, not a secret. The password and the hash are never returned here.
   """
   passwordCredential: ProjectUserPasswordCredential
+  """
+  Non-secret facts about the user's live (not revoked, not deleted) project-user API keys in the
+  request's project scope, oldest first. `null` outside a project scope or when the caller lacks
+  `ProjectUser:ExportCredentials` (never an error); `[]` for a member with no key. The secret, the
+  hash and the encrypted copy are never returned here.
+  """
+  apiKeyCredentials: [ProjectUserApiKeyCredential!]
   createdAt: Date!
   updatedAt: Date!
   deletedAt: Date

package/src/sdl-contract.test.ts

@@ -53,10 +53,11 @@ describe('operation documents', () => {
   // 137 after CDM imports by reference: RequestProjectSyncUploadUrlDocument.
   // 138 after operator-set-email: SetProjectUserEmailDocument.
   // 140 after operator-set-password: SetProjectUserPasswordDocument, ExportProjectUserCredentialsDocument.
+  // 141 after exportable-api-key-secret opt-in: SetProjectExportableApiKeySecretsDocument.
   // Updating this number is the point of the pin, not a nuisance: every change
   // to it should be a line in a commit message.
   it('finds every document under src/operations', () => {
-    expect(files).toHaveLength(140);
+    expect(files).toHaveLength(141);
   });
 
   it.each(files.map((f) => [relative(process.cwd(), f), f]))('%s validates', (_label, file) => {