AWS.ACMPCA reference

CertificateAuthority

Source: src/AWS/ACMPCA/CertificateAuthority.ts

An Amazon Web Services Private CA certificate authority.

A newly created CA starts in the PENDING_CERTIFICATE state — to activate it you must retrieve its CSR, sign it (self-sign for a root CA), and import the signed certificate. Private CAs bill a monthly fee for as long as they exist, so destroy test CAs promptly. Deletion places the CA in the DELETED state for a configurable 7-30 day restoration window.

CertificateAuthority: Creating a Certificate Authority

Root CA

import * as ACMPCA from "alchemy/AWS/ACMPCA";

const ca = yield* ACMPCA.CertificateAuthority("RootCA", {
  subject: { commonName: "corp.example.com" },
});

ECDSA Subordinate CA

const ca = yield* ACMPCA.CertificateAuthority("IssuingCA", {
  type: "SUBORDINATE",
  keyAlgorithm: "EC_prime256v1",
  signingAlgorithm: "SHA256WITHECDSA",
  subject: {
    commonName: "issuing.corp.example.com",
    organization: "Example Corp",
    country: "US",
  },
});

Short-Lived Certificate Mode

const ca = yield* ACMPCA.CertificateAuthority("ShortLivedCA", {
  subject: { commonName: "ephemeral.example.com" },
  usageMode: "SHORT_LIVED_CERTIFICATE",
});

CertificateAuthority: Revocation

const ca = yield* ACMPCA.CertificateAuthority("RootCA", {
  subject: { commonName: "corp.example.com" },
  revocationConfiguration: {
    crlConfiguration: {
      enabled: true,
      expiration: "7 days",
      s3BucketName: bucket.bucketName,
    },
  },
});

CertificateAuthority: Granting ACM Access

const permission = yield* ACMPCA.Permission("AcmRenewal", {
  certificateAuthorityArn: ca.certificateAuthorityArn,
});

CertificateAuthority: Reacting to CA Events

// ACM PCA emits lifecycle events (certificate issuance, expiry, CRL and
// audit-report generation) on the default EventBridge bus under the
// `aws.acm-pca` source — consume them with the generic EventBridge
// event source; there is no ACM PCA-specific notification config.
yield* AWS.EventBridge.consumeBusEvents(
  {
    source: ["aws.acm-pca"],
    "detail-type": ["ACM Private CA Certificate Issuance"],
  },
  (events) =>
    Stream.runForEach(events, (event) => Effect.log(event.detail)),
);

CertificateAuthorityPolicy

Source: src/AWS/ACMPCA/CertificateAuthorityPolicy.ts

A resource-based policy attached to a private CA, granting cross-account access — e.g. allowing a Certificate Manager (ACM) user in another account to issue and renew certificates signed by this CA. This is the policy Amazon Web Services Resource Access Manager (RAM) manages when a CA is shared; attach it directly for fine-grained control.

CertificateAuthorityPolicy: Attaching a CA Policy

import * as ACMPCA from "alchemy/AWS/ACMPCA";

const policy = yield* ACMPCA.CertificateAuthorityPolicy("CrossAccount", {
  certificateAuthorityArn: ca.certificateAuthorityArn,
  policy: {
    Version: "2012-10-17",
    Statement: [
      {
        Effect: "Allow",
        Principal: { AWS: "arn:aws:iam::123456789012:root" },
        Action: [
          "acm-pca:DescribeCertificateAuthority",
          "acm-pca:GetCertificate",
          "acm-pca:GetCertificateAuthorityCertificate",
          "acm-pca:ListPermissions",
          "acm-pca:IssueCertificate",
          "acm-pca:RevokeCertificate",
        ],
        Resource: ca.certificateAuthorityArn,
      },
    ],
  },
});

CreateCertificateAuthorityAuditReport

Source: src/AWS/ACMPCA/CreateCertificateAuthorityAuditReport.ts

Runtime binding for acm-pca:CreateCertificateAuthorityAuditReport.

Bind a CertificateAuthority inside a function runtime to generate an audit report of every private-key use (issue/revoke) into an S3 bucket — e.g. from a scheduled compliance function. AWS allows at most one report per CA every 30 minutes. The S3 bucket policy must grant Amazon Web Services Private CA write access. Provide ACMPCA.CreateCertificateAuthorityAuditReportHttp on the Function effect to implement the binding.

CreateCertificateAuthorityAuditReport: Audit Reports

// init
const createAuditReport =
  yield* ACMPCA.CreateCertificateAuthorityAuditReport(ca);

// runtime
const report = yield* createAuditReport({
  S3BucketName: bucketName,
  AuditReportResponseFormat: "JSON",
});
// report.AuditReportId / report.S3Key

DescribeCertificateAuthorityAuditReport

Source: src/AWS/ACMPCA/DescribeCertificateAuthorityAuditReport.ts

Runtime binding for acm-pca:DescribeCertificateAuthorityAuditReport.

Bind a CertificateAuthority inside a function runtime to check the status of an audit report started with CreateCertificateAuthorityAuditReport (reports are generated asynchronously into S3). Provide ACMPCA.DescribeCertificateAuthorityAuditReportHttp on the Function effect to implement the binding.

DescribeCertificateAuthorityAuditReport: Audit Reports

// init
const describeAuditReport =
  yield* ACMPCA.DescribeCertificateAuthorityAuditReport(ca);

// runtime
const status = yield* describeAuditReport({
  AuditReportId: report.AuditReportId!,
}).pipe(
  Effect.repeat({
    schedule: Schedule.spaced("2 seconds"),
    until: (r) => r.AuditReportStatus !== "CREATING",
    times: 10,
  }),
);

GetCertificate

Source: src/AWS/ACMPCA/GetCertificate.ts

Runtime binding for acm-pca:GetCertificate.

Bind a CertificateAuthority inside a function runtime to retrieve a certificate previously issued by the CA (via the IssueCertificate binding). Issuance is asynchronous — retry while the typed RequestInProgressException is observed. Provide ACMPCA.GetCertificateHttp on the Function effect to implement the binding.

GetCertificate: Retrieving Issued Certificates

// init
const getCertificate = yield* ACMPCA.GetCertificate(ca);

// runtime
const certificate = yield* getCertificate({
  CertificateArn: issued.CertificateArn!,
}).pipe(
  Effect.retry({
    while: (e) => e._tag === "RequestInProgressException",
    schedule: Schedule.exponential("500 millis"),
    times: 8,
  }),
);
// certificate.Certificate / certificate.CertificateChain (PEM)

GetCertificateAuthorityCertificate

Source: src/AWS/ACMPCA/GetCertificateAuthorityCertificate.ts

Runtime binding for acm-pca:GetCertificateAuthorityCertificate.

Bind a CertificateAuthority inside a function runtime to retrieve the CA’s own certificate and chain (PEM) — e.g. to build a trust store for mutual-TLS verification of certificates the CA issued. Provide ACMPCA.GetCertificateAuthorityCertificateHttp on the Function effect to implement the binding.

GetCertificateAuthorityCertificate: Reading the CA Certificate

// init
const getCaCertificate =
  yield* ACMPCA.GetCertificateAuthorityCertificate(ca);

// runtime
const { Certificate, CertificateChain } = yield* getCaCertificate();

GetCertificateAuthorityCsr

Source: src/AWS/ACMPCA/GetCertificateAuthorityCsr.ts

Runtime binding for acm-pca:GetCertificateAuthorityCsr.

Bind a CertificateAuthority inside a function runtime to retrieve the CSR the CA generated at creation. The CSR is the input to the CA activation flow: sign it (self-sign a root via IssueCertificate, or have an external parent CA sign it), then install the result with ImportCertificateAuthorityCertificate. Provide ACMPCA.GetCertificateAuthorityCsrHttp on the Function effect to implement the binding.

GetCertificateAuthorityCsr: CA Activation

// init
const getCsr = yield* ACMPCA.GetCertificateAuthorityCsr(ca);

// runtime
const { Csr } = yield* getCsr();

ImportCertificateAuthorityCertificate

Source: src/AWS/ACMPCA/ImportCertificateAuthorityCertificate.ts

Runtime binding for acm-pca:ImportCertificateAuthorityCertificate.

Bind a CertificateAuthority inside a function runtime to install the CA’s signed certificate — the final step of the activation flow (fetch CSR via GetCertificateAuthorityCsr, sign it, import). This enables workflows where the CA’s CSR is signed by an on-premises or external parent CA at runtime. Provide ACMPCA.ImportCertificateAuthorityCertificateHttp on the Function effect to implement the binding.

ImportCertificateAuthorityCertificate: CA Activation

// init
const importCaCertificate =
  yield* ACMPCA.ImportCertificateAuthorityCertificate(ca);

// runtime
yield* importCaCertificate({
  Certificate: new TextEncoder().encode(signedCertPem),
  CertificateChain: new TextEncoder().encode(chainPem),
});

IssueCertificate

Source: src/AWS/ACMPCA/IssueCertificate.ts

Runtime binding for acm-pca:IssueCertificate.

Bind a CertificateAuthority inside a function runtime to sign certificate signing requests (CSRs) with the CA’s private key. Returns the ARN of the issued certificate — retrieve the PEM with the GetCertificate binding (issuance is asynchronous, so poll while RequestInProgressException is observed). Provide ACMPCA.IssueCertificateHttp on the Function effect to implement the binding.

IssueCertificate: Issuing Certificates

// init
const issueCertificate = yield* ACMPCA.IssueCertificate(ca);

// runtime
const issued = yield* issueCertificate({
  Csr: new TextEncoder().encode(csrPem),
  SigningAlgorithm: "SHA256WITHRSA",
  Validity: { Type: "DAYS", Value: 7 },
});
// issued.CertificateArn

Permission

Source: src/AWS/ACMPCA/Permission.ts

A permission on a private CA granted to the Certificate Manager (ACM) service principal, allowing ACM to automatically issue and renew ACM certificates signed by the CA.

Permission: Granting Permissions

Allow ACM to auto-renew certificates

import * as ACMPCA from "alchemy/AWS/ACMPCA";

const permission = yield* ACMPCA.Permission("AcmRenewal", {
  certificateAuthorityArn: ca.certificateAuthorityArn,
});

Restrict the granted actions

const permission = yield* ACMPCA.Permission("AcmIssueOnly", {
  certificateAuthorityArn: ca.certificateAuthorityArn,
  actions: ["IssueCertificate", "GetCertificate"],
});

RevokeCertificate

Source: src/AWS/ACMPCA/RevokeCertificate.ts

Runtime binding for acm-pca:RevokeCertificate.

Bind a CertificateAuthority inside a function runtime to revoke certificates the CA issued (e.g. on credential compromise). Revoked certificates appear in the CA’s CRL/OCSP responses when revocation is configured. The serial number is the hex serial from the issued certificate. Provide ACMPCA.RevokeCertificateHttp on the Function effect to implement the binding.

RevokeCertificate: Revoking Certificates

// init
const revokeCertificate = yield* ACMPCA.RevokeCertificate(ca);

// runtime
yield* revokeCertificate({
  CertificateSerial: serialHex,
  RevocationReason: "KEY_COMPROMISE",
});