@grantjs/schema 1.14.3 → 1.16.0

package/package.json

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

package/src/generated/graphql.ts

@@ -1465,6 +1465,10 @@ export type ProjectSyncJobQuery = {
       usersCreated: number;
       userRolesAssigned: number;
       projectUserApiKeysCreated: number;
+      passwordsImported: number;
+      passwordsUpdated: number;
+      passwordsUnchanged: number;
+      passwordsSkippedExisting: number;
       warnings: Array<string>;
     } | null;
   };
@@ -1505,6 +1509,22 @@ export type ProjectSyncJobsQuery = {
   };
 };
 
+export type RequestProjectSyncUploadUrlMutationVariables = Exact<{
+  id: string | number;
+  scope: Types.Scope;
+  input: Types.RequestProjectSyncUploadUrlInput;
+}>;
+
+export type RequestProjectSyncUploadUrlMutation = {
+  requestProjectSyncUploadUrl: {
+    uploadId: string;
+    url: string;
+    method: string;
+    expiresAt: Date;
+    headers: Array<{ name: string; value: string }>;
+  };
+};
+
 export type StartProjectExportMutationVariables = Exact<{
   id: string | number;
   scope: Types.Scope;
@@ -8001,6 +8021,10 @@ export const ProjectSyncJobDocument = {
                       { kind: 'Field', name: { kind: 'Name', value: 'usersCreated' } },
                       { kind: 'Field', name: { kind: 'Name', value: 'userRolesAssigned' } },
                       { kind: 'Field', name: { kind: 'Name', value: 'projectUserApiKeysCreated' } },
+                      { kind: 'Field', name: { kind: 'Name', value: 'passwordsImported' } },
+                      { 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: 'warnings' } },
                     ],
                   },
@@ -8153,6 +8177,94 @@ export const ProjectSyncJobsDocument = {
     },
   ],
 } as unknown as DocumentNode<ProjectSyncJobsQuery, ProjectSyncJobsQueryVariables>;
+export const RequestProjectSyncUploadUrlDocument = {
+  kind: 'Document',
+  definitions: [
+    {
+      kind: 'OperationDefinition',
+      operation: 'mutation',
+      name: { kind: 'Name', value: 'RequestProjectSyncUploadUrl' },
+      variableDefinitions: [
+        {
+          kind: 'VariableDefinition',
+          variable: { kind: 'Variable', name: { kind: 'Name', value: 'id' } },
+          type: {
+            kind: 'NonNullType',
+            type: { kind: 'NamedType', name: { kind: 'Name', value: 'ID' } },
+          },
+        },
+        {
+          kind: 'VariableDefinition',
+          variable: { kind: 'Variable', name: { kind: 'Name', value: 'scope' } },
+          type: {
+            kind: 'NonNullType',
+            type: { kind: 'NamedType', name: { kind: 'Name', value: 'Scope' } },
+          },
+        },
+        {
+          kind: 'VariableDefinition',
+          variable: { kind: 'Variable', name: { kind: 'Name', value: 'input' } },
+          type: {
+            kind: 'NonNullType',
+            type: {
+              kind: 'NamedType',
+              name: { kind: 'Name', value: 'RequestProjectSyncUploadUrlInput' },
+            },
+          },
+        },
+      ],
+      selectionSet: {
+        kind: 'SelectionSet',
+        selections: [
+          {
+            kind: 'Field',
+            name: { kind: 'Name', value: 'requestProjectSyncUploadUrl' },
+            arguments: [
+              {
+                kind: 'Argument',
+                name: { kind: 'Name', value: 'id' },
+                value: { kind: 'Variable', name: { kind: 'Name', value: 'id' } },
+              },
+              {
+                kind: 'Argument',
+                name: { kind: 'Name', value: 'scope' },
+                value: { kind: 'Variable', name: { kind: 'Name', value: 'scope' } },
+              },
+              {
+                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: 'uploadId' } },
+                { kind: 'Field', name: { kind: 'Name', value: 'url' } },
+                { kind: 'Field', name: { kind: 'Name', value: 'method' } },
+                { kind: 'Field', name: { kind: 'Name', value: 'expiresAt' } },
+                {
+                  kind: 'Field',
+                  name: { kind: 'Name', value: 'headers' },
+                  selectionSet: {
+                    kind: 'SelectionSet',
+                    selections: [
+                      { kind: 'Field', name: { kind: 'Name', value: 'name' } },
+                      { kind: 'Field', name: { kind: 'Name', value: 'value' } },
+                    ],
+                  },
+                },
+              ],
+            },
+          },
+        ],
+      },
+    },
+  ],
+} as unknown as DocumentNode<
+  RequestProjectSyncUploadUrlMutation,
+  RequestProjectSyncUploadUrlMutationVariables
+>;
 export const StartProjectExportDocument = {
   kind: 'Document',
   definitions: [

package/src/generated/resolvers.ts

@@ -237,6 +237,8 @@ export type ResolversTypes = ResolversObject<{
   CdmModeInput: Types.CdmModeInput;
   CdmModeStrategy: Types.CdmModeStrategy;
   CdmOnConflict: Types.CdmOnConflict;
+  CdmPasswordAlgorithm: Types.CdmPasswordAlgorithm;
+  CdmPasswordInput: Types.CdmPasswordInput;
   ChangeMyPasswordInput: Types.ChangeMyPasswordInput;
   ChangeMyPasswordResult: ResolverTypeWrapper<Types.ChangeMyPasswordResult>;
   ClearProjectAppPictureInput: Types.ClearProjectAppPictureInput;
@@ -378,6 +380,7 @@ export type ResolversTypes = ResolversObject<{
   ProjectSyncJobSortInput: Types.ProjectSyncJobSortInput;
   ProjectSyncJobSortableField: Types.ProjectSyncJobSortableField;
   ProjectSyncJobStatus: Types.ProjectSyncJobStatus;
+  ProjectSyncUploadUrl: ResolverTypeWrapper<Types.ProjectSyncUploadUrl>;
   ProjectTag: ResolverTypeWrapper<Types.ProjectTag>;
   ProjectUser: ResolverTypeWrapper<Types.ProjectUser>;
   ProjectUserApiKey: ResolverTypeWrapper<Types.ProjectUserApiKey>;
@@ -464,6 +467,7 @@ export type ResolversTypes = ResolversObject<{
   RequestPasswordResetResponse: ResolverTypeWrapper<Types.RequestPasswordResetResponse>;
   RequestProjectAppPictureUploadUrlInput: Types.RequestProjectAppPictureUploadUrlInput;
   RequestProjectPictureUploadUrlInput: Types.RequestProjectPictureUploadUrlInput;
+  RequestProjectSyncUploadUrlInput: Types.RequestProjectSyncUploadUrlInput;
   RequestUserPictureUploadUrlInput: Types.RequestUserPictureUploadUrlInput;
   ResendVerificationInput: Types.ResendVerificationInput;
   ResendVerificationResponse: ResolverTypeWrapper<Types.ResendVerificationResponse>;
@@ -502,6 +506,7 @@ export type ResolversTypes = ResolversObject<{
   String: ResolverTypeWrapper<Types.Scalars['String']['output']>;
   SyncProjectInput: Types.SyncProjectInput;
   SyncProjectResult: ResolverTypeWrapper<Types.SyncProjectResult>;
+  SyncProjectSourceInput: Types.SyncProjectSourceInput;
   Tag: ResolverTypeWrapper<Types.Tag>;
   TagCdmInput: Types.TagCdmInput;
   TagPage: ResolverTypeWrapper<Types.TagPage>;
@@ -643,6 +648,7 @@ export type ResolversParentTypes = ResolversObject<{
   Boolean: Types.Scalars['Boolean']['output'];
   CdmKeyResolverInput: Types.CdmKeyResolverInput;
   CdmModeInput: Types.CdmModeInput;
+  CdmPasswordInput: Types.CdmPasswordInput;
   ChangeMyPasswordInput: Types.ChangeMyPasswordInput;
   ChangeMyPasswordResult: Types.ChangeMyPasswordResult;
   ClearProjectAppPictureInput: Types.ClearProjectAppPictureInput;
@@ -759,6 +765,7 @@ export type ResolversParentTypes = ResolversObject<{
   ProjectSyncJob: Types.ProjectSyncJob;
   ProjectSyncJobPage: Types.ProjectSyncJobPage;
   ProjectSyncJobSortInput: Types.ProjectSyncJobSortInput;
+  ProjectSyncUploadUrl: Types.ProjectSyncUploadUrl;
   ProjectTag: Types.ProjectTag;
   ProjectUser: Types.ProjectUser;
   ProjectUserApiKey: Types.ProjectUserApiKey;
@@ -845,6 +852,7 @@ export type ResolversParentTypes = ResolversObject<{
   RequestPasswordResetResponse: Types.RequestPasswordResetResponse;
   RequestProjectAppPictureUploadUrlInput: Types.RequestProjectAppPictureUploadUrlInput;
   RequestProjectPictureUploadUrlInput: Types.RequestProjectPictureUploadUrlInput;
+  RequestProjectSyncUploadUrlInput: Types.RequestProjectSyncUploadUrlInput;
   RequestUserPictureUploadUrlInput: Types.RequestUserPictureUploadUrlInput;
   ResendVerificationInput: Types.ResendVerificationInput;
   ResendVerificationResponse: Types.ResendVerificationResponse;
@@ -878,6 +886,7 @@ export type ResolversParentTypes = ResolversObject<{
   String: Types.Scalars['String']['output'];
   SyncProjectInput: Types.SyncProjectInput;
   SyncProjectResult: Types.SyncProjectResult;
+  SyncProjectSourceInput: Types.SyncProjectSourceInput;
   Tag: Types.Tag;
   TagCdmInput: Types.TagCdmInput;
   TagPage: Types.TagPage;
@@ -1839,6 +1848,12 @@ export type MutationResolvers<
     ContextType,
     RequireFields<Types.MutationRequestProjectPictureUploadUrlArgs, 'input'>
   >;
+  requestProjectSyncUploadUrl?: Resolver<
+    ResolversTypes['ProjectSyncUploadUrl'],
+    ParentType,
+    ContextType,
+    RequireFields<Types.MutationRequestProjectSyncUploadUrlArgs, 'id' | 'input' | 'scope'>
+  >;
   requestUserPictureUploadUrl?: Resolver<
     ResolversTypes['UploadUrl'],
     ParentType,
@@ -2733,6 +2748,18 @@ export type ProjectSyncJobPageResolvers<
   __isTypeOf?: IsTypeOfResolverFn<ParentType, ContextType>;
 }>;
 
+export type ProjectSyncUploadUrlResolvers<
+  ContextType = any,
+  ParentType extends ResolversParentTypes['ProjectSyncUploadUrl'] =
+    ResolversParentTypes['ProjectSyncUploadUrl'],
+> = ResolversObject<{
+  expiresAt?: Resolver<ResolversTypes['Date'], ParentType, ContextType>;
+  headers?: Resolver<Array<ResolversTypes['UploadUrlHeader']>, ParentType, ContextType>;
+  method?: Resolver<ResolversTypes['String'], ParentType, ContextType>;
+  uploadId?: Resolver<ResolversTypes['ID'], ParentType, ContextType>;
+  url?: Resolver<ResolversTypes['String'], ParentType, ContextType>;
+}>;
+
 export type ProjectTagResolvers<
   ContextType = any,
   ParentType extends ResolversParentTypes['ProjectTag'] = ResolversParentTypes['ProjectTag'],
@@ -3264,6 +3291,10 @@ export type SyncProjectResultResolvers<
   groupTagsLinked?: Resolver<ResolversTypes['Int'], ParentType, ContextType>;
   groupsCreated?: Resolver<ResolversTypes['Int'], ParentType, ContextType>;
   importId?: Resolver<Types.Maybe<ResolversTypes['String']>, ParentType, ContextType>;
+  passwordsImported?: Resolver<ResolversTypes['Int'], ParentType, ContextType>;
+  passwordsSkippedExisting?: Resolver<ResolversTypes['Int'], ParentType, ContextType>;
+  passwordsUnchanged?: Resolver<ResolversTypes['Int'], ParentType, ContextType>;
+  passwordsUpdated?: Resolver<ResolversTypes['Int'], ParentType, ContextType>;
   permissionsCreated?: Resolver<ResolversTypes['Int'], ParentType, ContextType>;
   projectGroupsLinked?: Resolver<ResolversTypes['Int'], ParentType, ContextType>;
   projectId?: Resolver<ResolversTypes['ID'], ParentType, ContextType>;
@@ -3760,6 +3791,7 @@ export type Resolvers<ContextType = any> = ResolversObject<{
   ProjectRolePermission?: ProjectRolePermissionResolvers<ContextType>;
   ProjectSyncJob?: ProjectSyncJobResolvers<ContextType>;
   ProjectSyncJobPage?: ProjectSyncJobPageResolvers<ContextType>;
+  ProjectSyncUploadUrl?: ProjectSyncUploadUrlResolvers<ContextType>;
   ProjectTag?: ProjectTagResolvers<ContextType>;
   ProjectUser?: ProjectUserResolvers<ContextType>;
   ProjectUserApiKey?: ProjectUserApiKeyResolvers<ContextType>;

package/src/generated/schema-types.ts

@@ -448,8 +448,9 @@ export enum CdmIfMissing {
 export type CdmKeyResolverInput = {
   /**
    * `id` references an existing Grant user id. `email` resolves or creates a
-   * global passwordless email authentication method. Other values are treated as
-   * CDM-local external keys for project import/export.
+   * global email authentication method, passwordless unless the user carries a
+   * `password`. Other values are treated as CDM-local external keys for project
+   * import/export.
    */
   findBy?: InputMaybe<CdmFindBy>;
   ifMissing?: InputMaybe<CdmIfMissing>;
@@ -479,6 +480,31 @@ export enum CdmOnConflict {
   Update = 'update',
 }
 
+/**
+ * Password hash algorithms a CDM import can carry. Only `bcrypt` is accepted; the
+ * enum leaves room for further algorithms without changing the input shape.
+ */
+export enum CdmPasswordAlgorithm {
+  Bcrypt = 'bcrypt',
+}
+
+/**
+ * A password hash the importer already holds, to be stored as the user's email
+ * password credential (ADR 0010). Never the plaintext password.
+ */
+export type CdmPasswordInput = {
+  algorithm: CdmPasswordAlgorithm;
+  /**
+   * A bcrypt hash in the modular-crypt form `$2a$`, `$2b$` or `$2y$`, a two-digit
+   * cost and 53 salt-and-hash characters (60 in all), such as the output of Go's
+   * `bcrypt.GenerateFromPassword`. The cost must be within the range the deployment
+   * accepts (4 to 15). It is written only to the credential store: it is not kept in
+   * metadata, searchable tokens, audit values, events or the stored job payload once
+   * the job finishes, and an invalid hash is refused without being echoed.
+   */
+  hash: Scalars['String']['input'];
+};
+
 export type ChangeMyPasswordInput = {
   confirmPassword: Scalars['String']['input'];
   /** Required when a password already exists; omit when setting the first password. */
@@ -1191,6 +1217,19 @@ export type Mutation = {
    * is recorded against the project.
    */
   requestProjectPictureUploadUrl: UploadUrl;
+  /**
+   * Ask for a URL to upload a CDM import document directly to storage, so it can be
+   * imported without passing through this API's request body (and its size limit).
+   *
+   * Requires Project sync job update permission in the given project scope, like
+   * `startProjectSync`. The server derives the storage key from the project and a
+   * server-minted `uploadId`; the client never supplies a path. The URL commits to exactly
+   * `input.contentLength` bytes of `application/json`, up to `CDM_UPLOAD_MAX_BYTES`.
+   *
+   * PUT the file, then call `startProjectSync` with `input.source.uploadId`. An upload
+   * that is never started is expired by the storage lifecycle rule.
+   */
+  requestProjectSyncUploadUrl: ProjectSyncUploadUrl;
   /**
    * Ask for a URL to upload another user's picture directly to storage.
    *
@@ -1519,6 +1558,12 @@ export type MutationRequestProjectPictureUploadUrlArgs = {
   input: RequestProjectPictureUploadUrlInput;
 };
 
+export type MutationRequestProjectSyncUploadUrlArgs = {
+  id: Scalars['ID']['input'];
+  input: RequestProjectSyncUploadUrlInput;
+  scope: Scope;
+};
+
 export type MutationRequestUserPictureUploadUrlArgs = {
   input: RequestUserPictureUploadUrlInput;
 };
@@ -2382,6 +2427,28 @@ export enum ProjectSyncJobStatus {
   Running = 'RUNNING',
 }
 
+/**
+ * A bounded, time-limited URL to PUT a CDM import document to, and the id to start the
+ * import from. Same commitments as `UploadUrl`: exactly `contentLength` bytes of exactly
+ * `contentType`, at a path derived on the server from the project, until `expiresAt`.
+ */
+export type ProjectSyncUploadUrl = {
+  __typename?: 'ProjectSyncUploadUrl';
+  /** Instant after which the store refuses the URL. */
+  expiresAt: Scalars['Date']['output'];
+  /** Headers the client must set verbatim. `Content-Length` is deliberately absent. */
+  headers: Array<UploadUrlHeader>;
+  /** HTTP method the client must use. Always PUT today. */
+  method: Scalars['String']['output'];
+  /** Pass as `source.uploadId` to `startProjectSync`. */
+  uploadId: Scalars['ID']['output'];
+  /**
+   * Absolute for object stores; application-relative for targets this API serves
+   * itself. Resolve it against the API origin before using it.
+   */
+  url: Scalars['String']['output'];
+};
+
 export type ProjectTag = Auditable & {
   __typename?: 'ProjectTag';
   createdAt: Scalars['Date']['output'];
@@ -3144,6 +3211,16 @@ export type RequestProjectPictureUploadUrlInput = {
   scope: Scope;
 };
 
+export type RequestProjectSyncUploadUrlInput = {
+  /**
+   * Exact byte length of the CDM JSON file the client will PUT. The URL commits to it,
+   * and it may not exceed `CDM_UPLOAD_MAX_BYTES` (default 64 MiB).
+   */
+  contentLength: Scalars['Int']['input'];
+  /** Defaults to `application/json`, the only type accepted. */
+  contentType?: InputMaybe<Scalars['String']['input']>;
+};
+
 export type RequestUserPictureUploadUrlInput = {
   /**
    * Exact byte length the client will send. Validated against the upload policy
@@ -3499,6 +3576,13 @@ export type StartProjectExportInput = {
 /**
  * Versioned canonical project document (CDM) for export/import: roles, users,
  * resources, permissions, groups, and tags scoped to one project.
+ *
+ * Two shapes. **Inline**: `version`, `roles` and `users` are required and the document is
+ * the input. **By reference**: `source` is set, `mode` still says how to apply it, and
+ * `version` is optional and the entity arrays (`roles`, `users`, `resources`,
+ * `permissions`, `groups`, `tags`) must be absent: the document is the file uploaded
+ * through `requestProjectSyncUploadUrl`, and the worker validates it, so a schema error or
+ * an over-limit entity count surfaces as a `FAILED` job, not as an error on the mutation.
  */
 export type SyncProjectInput = {
   groups?: InputMaybe<Array<GroupCdmInput>>;
@@ -3506,10 +3590,19 @@ export type SyncProjectInput = {
   mode: CdmModeInput;
   permissions?: InputMaybe<Array<PermissionCdmInput>>;
   resources?: InputMaybe<Array<ResourceCdmInput>>;
-  roles: Array<RoleCdmInput>;
+  /** Required inline; must be absent with `source`. */
+  roles?: InputMaybe<Array<RoleCdmInput>>;
+  /**
+   * Import the document uploaded through `requestProjectSyncUploadUrl` instead of sending
+   * it inline. The entity arrays must then be absent, and `mode` (and `version`, if
+   * given) must match the uploaded document.
+   */
+  source?: InputMaybe<SyncProjectSourceInput>;
   tags?: InputMaybe<Array<TagCdmInput>>;
-  users: Array<UserCdmInput>;
-  version: Scalars['Int']['input'];
+  /** Required inline; must be absent with `source`. */
+  users?: InputMaybe<Array<UserCdmInput>>;
+  /** Required inline; optional with `source`, where the uploaded document carries it. */
+  version?: InputMaybe<Scalars['Int']['input']>;
 };
 
 /** Counters and warnings from a completed CDM import. */
@@ -3519,6 +3612,22 @@ export type SyncProjectResult = {
   groupTagsLinked: Scalars['Int']['output'];
   groupsCreated: Scalars['Int']['output'];
   importId?: Maybe<Scalars['String']['output']>;
+  /** Users whose `password` hash was stored as their email credential for the first time. */
+  passwordsImported: Scalars['Int']['output'];
+  /**
+   * Users whose `password` hash was not stored because the credential or the identity is
+   * not the import's to write: a password set in Grant, an address the owner has verified,
+   * or an identity that already existed and was not created by an earlier import of this
+   * project.
+   */
+  passwordsSkippedExisting: Scalars['Int']['output'];
+  /** Users whose imported credential already equalled the hash in the document. */
+  passwordsUnchanged: Scalars['Int']['output'];
+  /**
+   * Users whose imported credential was replaced because the document carried a different
+   * hash for it.
+   */
+  passwordsUpdated: Scalars['Int']['output'];
   permissionsCreated: Scalars['Int']['output'];
   projectGroupsLinked: Scalars['Int']['output'];
   projectId: Scalars['ID']['output'];
@@ -3539,6 +3648,24 @@ export type SyncProjectResult = {
   warnings: Array<Scalars['String']['output']>;
 };
 
+/**
+ * Where the CDM document of a by-reference import is: an upload made through
+ * `requestProjectSyncUploadUrl`. See `SyncProjectInput.source`.
+ */
+export type SyncProjectSourceInput = {
+  /**
+   * How many entities (roles, users, resources, permissions, groups and tags) the
+   * uploaded document holds. A hint, recorded for the job list and never trusted: the
+   * worker counts the document itself.
+   */
+  entityCount?: InputMaybe<Scalars['Int']['input']>;
+  /**
+   * The `uploadId` returned by `requestProjectSyncUploadUrl`. The server derives the
+   * storage key from the project and this id; the client never supplies a path.
+   */
+  uploadId: Scalars['ID']['input'];
+};
+
 export type Tag = Auditable & {
   __typename?: 'Tag';
   color: Scalars['String']['output'];
@@ -4004,6 +4131,22 @@ export type UserCdmInput = {
   key: CdmKeyResolverInput;
   metadata?: InputMaybe<Scalars['JSON']['input']>;
   name: Scalars['String']['input'];
+  /**
+   * Existing password credential to import for this user. Only valid with
+   * `key.findBy: email`, because the credential lives on the email authentication
+   * method; any other resolver is a validation error.
+   *
+   * Ownership is forward-only. An imported credential is marked as imported and stays
+   * owned by the importing system while the email is unverified: a later import of this
+   * project with a different hash replaces it, an identical one changes nothing. Once the
+   * owner verifies the address, or the password is set, changed or reset in Grant, Grant owns
+   * it and imports never touch it again. A credential is written only for an identity the
+   * import creates, or one an earlier import of this project created whose email is still
+   * unverified; any other existing identity, including one found through GitHub or Google,
+   * is left untouched. An absent `password` never removes a
+   * stored credential. See `SyncProjectResult` for the counters.
+   */
+  password?: InputMaybe<CdmPasswordInput>;
   /** Direct user → permission grants (document keys or catalog `resourceSlug:action` refs). */
   permissions?: InputMaybe<Array<Scalars['String']['input']>>;
   primaryTag?: InputMaybe<Scalars['String']['input']>;

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

@@ -22,6 +22,10 @@ query ProjectSyncJob($id: ID!, $scope: Scope!, $jobId: ID!) {
       usersCreated
       userRolesAssigned
       projectUserApiKeysCreated
+      passwordsImported
+      passwordsUpdated
+      passwordsUnchanged
+      passwordsSkippedExisting
       warnings
     }
     warnings

package/src/operations/projects/request-project-sync-upload-url.graphql

@@ -0,0 +1,16 @@
+mutation RequestProjectSyncUploadUrl(
+  $id: ID!
+  $scope: Scope!
+  $input: RequestProjectSyncUploadUrlInput!
+) {
+  requestProjectSyncUploadUrl(id: $id, scope: $scope, input: $input) {
+    uploadId
+    url
+    method
+    expiresAt
+    headers {
+      name
+      value
+    }
+  }
+}

package/src/schema/projects/inputs/request-project-sync-upload-url.graphql

@@ -0,0 +1,9 @@
+input RequestProjectSyncUploadUrlInput {
+  """
+  Exact byte length of the CDM JSON file the client will PUT. The URL commits to it,
+  and it may not exceed `CDM_UPLOAD_MAX_BYTES` (default 64 MiB).
+  """
+  contentLength: Int!
+  "Defaults to `application/json`, the only type accepted."
+  contentType: String
+}

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

@@ -23,6 +23,14 @@ enum CdmIfMissing {
   createNew
 }
 
+"""
+Password hash algorithms a CDM import can carry. Only `bcrypt` is accepted; the
+enum leaves room for further algorithms without changing the input shape.
+"""
+enum CdmPasswordAlgorithm {
+  bcrypt
+}
+
 input CdmModeInput {
   strategy: CdmModeStrategy!
   onConflict: CdmOnConflict
@@ -39,8 +47,9 @@ input CdmKeyResolverInput {
   value: String!
   """
   `id` references an existing Grant user id. `email` resolves or creates a
-  global passwordless email authentication method. Other values are treated as
-  CDM-local external keys for project import/export.
+  global email authentication method, passwordless unless the user carries a
+  `password`. Other values are treated as CDM-local external keys for project
+  import/export.
   """
   findBy: CdmFindBy
   ifMissing: CdmIfMissing
@@ -128,6 +137,23 @@ input UserApiKeyCdmInput {
   metadata: JSON
 }
 
+"""
+A password hash the importer already holds, to be stored as the user's email
+password credential (ADR 0010). Never the plaintext password.
+"""
+input CdmPasswordInput {
+  algorithm: CdmPasswordAlgorithm!
+  """
+  A bcrypt hash in the modular-crypt form `$2a$`, `$2b$` or `$2y$`, a two-digit
+  cost and 53 salt-and-hash characters (60 in all), such as the output of Go's
+  `bcrypt.GenerateFromPassword`. The cost must be within the range the deployment
+  accepts (4 to 15). It is written only to the credential store: it is not kept in
+  metadata, searchable tokens, audit values, events or the stored job payload once
+  the job finishes, and an invalid hash is refused without being echoed.
+  """
+  hash: String!
+}
+
 input UserCdmInput {
   key: CdmKeyResolverInput!
   name: String!
@@ -147,24 +173,74 @@ input UserCdmInput {
   primaryTag: String
   apiKeys: [UserApiKeyCdmInput!]
   """
+  Existing password credential to import for this user. Only valid with
+  `key.findBy: email`, because the credential lives on the email authentication
+  method; any other resolver is a validation error.
+
+  Ownership is forward-only. An imported credential is marked as imported and stays
+  owned by the importing system while the email is unverified: a later import of this
+  project with a different hash replaces it, an identical one changes nothing. Once the
+  owner verifies the address, or the password is set, changed or reset in Grant, Grant owns
+  it and imports never touch it again. A credential is written only for an identity the
+  import creates, or one an earlier import of this project created whose email is still
+  unverified; any other existing identity, including one found through GitHub or Google,
+  is left untouched. An absent `password` never removes a
+  stored credential. See `SyncProjectResult` for the counters.
+  """
+  password: CdmPasswordInput
+  """
   Denormalized search tokens for project-scoped user list views.
   """
   searchable: JSON
   metadata: JSON
 }
 
+"""
+Where the CDM document of a by-reference import is: an upload made through
+`requestProjectSyncUploadUrl`. See `SyncProjectInput.source`.
+"""
+input SyncProjectSourceInput {
+  """
+  The `uploadId` returned by `requestProjectSyncUploadUrl`. The server derives the
+  storage key from the project and this id; the client never supplies a path.
+  """
+  uploadId: ID!
+  """
+  How many entities (roles, users, resources, permissions, groups and tags) the
+  uploaded document holds. A hint, recorded for the job list and never trusted: the
+  worker counts the document itself.
+  """
+  entityCount: Int
+}
+
 """
 Versioned canonical project document (CDM) for export/import: roles, users,
 resources, permissions, groups, and tags scoped to one project.
+
+Two shapes. **Inline**: `version`, `roles` and `users` are required and the document is
+the input. **By reference**: `source` is set, `mode` still says how to apply it, and
+`version` is optional and the entity arrays (`roles`, `users`, `resources`,
+`permissions`, `groups`, `tags`) must be absent: the document is the file uploaded
+through `requestProjectSyncUploadUrl`, and the worker validates it, so a schema error or
+an over-limit entity count surfaces as a `FAILED` job, not as an error on the mutation.
 """
 input SyncProjectInput {
-  version: Int!
+  "Required inline; optional with `source`, where the uploaded document carries it."
+  version: Int
   id: String
   mode: CdmModeInput!
-  roles: [RoleCdmInput!]!
-  users: [UserCdmInput!]!
+  "Required inline; must be absent with `source`."
+  roles: [RoleCdmInput!]
+  "Required inline; must be absent with `source`."
+  users: [UserCdmInput!]
   resources: [ResourceCdmInput!]
   permissions: [PermissionCdmInput!]
   groups: [GroupCdmInput!]
   tags: [TagCdmInput!]
+  """
+  Import the document uploaded through `requestProjectSyncUploadUrl` instead of sending
+  it inline. The entity arrays must then be absent, and `mode` (and `version`, if
+  given) must match the uploaded document.
+  """
+  source: SyncProjectSourceInput
 }

package/src/schema/projects/mutations/request-project-sync-upload-url.graphql

@@ -0,0 +1,19 @@
+extend type Mutation {
+  """
+  Ask for a URL to upload a CDM import document directly to storage, so it can be
+  imported without passing through this API's request body (and its size limit).
+
+  Requires Project sync job update permission in the given project scope, like
+  `startProjectSync`. The server derives the storage key from the project and a
+  server-minted `uploadId`; the client never supplies a path. The URL commits to exactly
+  `input.contentLength` bytes of `application/json`, up to `CDM_UPLOAD_MAX_BYTES`.
+
+  PUT the file, then call `startProjectSync` with `input.source.uploadId`. An upload
+  that is never started is expired by the storage lifecycle rule.
+  """
+  requestProjectSyncUploadUrl(
+    id: ID!
+    scope: Scope!
+    input: RequestProjectSyncUploadUrlInput!
+  ): ProjectSyncUploadUrl!
+}

package/src/schema/projects/types/project-sync-upload-url.graphql

@@ -0,0 +1,24 @@
+"""
+A bounded, time-limited URL to PUT a CDM import document to, and the id to start the
+import from. Same commitments as `UploadUrl`: exactly `contentLength` bytes of exactly
+`contentType`, at a path derived on the server from the project, until `expiresAt`.
+"""
+type ProjectSyncUploadUrl {
+  "Pass as `source.uploadId` to `startProjectSync`."
+  uploadId: ID!
+
+  """
+  Absolute for object stores; application-relative for targets this API serves
+  itself. Resolve it against the API origin before using it.
+  """
+  url: String!
+
+  "HTTP method the client must use. Always PUT today."
+  method: String!
+
+  "Headers the client must set verbatim. `Content-Length` is deliberately absent."
+  headers: [UploadUrlHeader!]!
+
+  "Instant after which the store refuses the URL."
+  expiresAt: Date!
+}

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

@@ -16,6 +16,26 @@ type SyncProjectResult {
   usersCreated: Int!
   userRolesAssigned: Int!
   projectUserApiKeysCreated: Int!
+  """
+  Users whose `password` hash was stored as their email credential for the first time.
+  """
+  passwordsImported: Int!
+  """
+  Users whose imported credential was replaced because the document carried a different
+  hash for it.
+  """
+  passwordsUpdated: Int!
+  """
+  Users whose imported credential already equalled the hash in the document.
+  """
+  passwordsUnchanged: Int!
+  """
+  Users whose `password` hash was not stored because the credential or the identity is
+  not the import's to write: a password set in Grant, an address the owner has verified,
+  or an identity that already existed and was not created by an earlier import of this
+  project.
+  """
+  passwordsSkippedExisting: Int!
   resourcesCreated: Int!
   permissionsCreated: Int!
   tagsCreated: Int!

package/src/sdl-contract.test.ts

@@ -50,10 +50,11 @@ describe('operation documents', () => {
   // project-app pictures (eight operation documents).
   // 135 after project OAuth connections: get/upsert/clear (three operation documents).
   // 136 after closed-install: AuthSignupPolicyDocument (publicSignupEnabled, bootstrapOpen).
+  // 137 after CDM imports by reference: RequestProjectSyncUploadUrlDocument.
   // 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(136);
+    expect(files).toHaveLength(137);
   });
 
   it.each(files.map((f) => [relative(process.cwd(), f), f]))('%s validates', (_label, file) => {