s3-test-server 1.0.1 → 2.1.0

package/README.md

@@ -2,18 +2,12 @@
 
 A lightweight Amazon S3 emulator for local development and testing.
 
-Zero runtime dependencies, a single small package, and wire-level
-compatibility with both old and new S3 clients:
-
-- **AWS SDK for JavaScript v3**, including flexible checksums
-  (CRC32, CRC32C, CRC64NVME, SHA1, SHA256), `aws-chunked` streaming uploads
-  with trailers, and full-object / composite multipart checksums
-- **AWS SDK for JavaScript v2**, SigV4 and legacy SigV2 (`signatureVersion: 's3'`)
-- **Any other S3 client** that signs with Signature V2 or V4, header-based or
-  presigned, path-style or virtual-host-style
-
-Data is stored on the filesystem (a temp directory by default), so it survives
-restarts when you point it at a directory of your own.
+Zero runtime dependencies and wire-level compatibility with old and new S3
+clients: AWS SDK for JavaScript v3 (flexible checksums, `aws-chunked`
+streaming, multipart), v2 (SigV4 and legacy SigV2), and any other client that
+signs with Signature V2/V4, header-based or presigned, path-style or
+virtual-host-style. Objects are stored on the filesystem and persist across
+restarts when you point `directory` at a folder of your own.
 
 ## Quick start
 
@@ -82,7 +76,7 @@ map to 127.0.0.1):
 ```js
 const server = new S3TestServer({
   address: 'aws-s3.local',
-  configureBuckets: [{ name: 'reports' }],
+  configureBuckets: [{ name: 'reports', acl: 'public-read' }],
 });
 
 beforeAll(() => server.run()); // http://aws-s3.local:4568
@@ -108,44 +102,141 @@ multipart thresholds, this test fails, exactly as it would against AWS.
 All options are optional. `new S3TestServer()` starts an HTTP server on
 `localhost:4568` backed by a temporary directory.
 
-### Server
-
-- `address` (string, default `'localhost'`): hostname or IP to bind to.
-- `port` (number, default `4568`): port to listen on. Use `0` for an
-  ephemeral port.
-- `key`, `cert` (string | Buffer): TLS key and certificate. Provide both to
-  serve HTTPS.
-- `silent` (boolean, default `false`): suppress log output.
-
-### Storage
-
-- `directory` (string, default: a temporary directory): where buckets and
-  objects are stored. Data persists across restarts.
-- `resetOnStart` (boolean, default `false`): clear the data directory on
-  every start, so a persistent `directory` begins empty.
-- `resetOnClose` (boolean, default `false`): delete all bucket data when
-  `close()` is called.
-- `configureBuckets` (array, default `[]`): buckets to create at startup,
-  each `{ name, configs }` with optional raw XML configs (CORS, website,
-  tagging).
-
-### Credentials and addressing
-
-- `accessKeyId` (string, default `'S3TEST'`): access key clients must sign
-  with.
-- `secretAccessKey` (string, default `'S3TEST'`): matching secret key.
-- `region` (string, default `'us-east-1'`): region reported in responses and
-  event records.
-- `vhostBuckets` (boolean, default `true`): virtual-host-style addressing
-  (`bucket.localhost`, `bucket.s3.<region>.amazonaws.com`).
-- `serviceEndpoint` (string, default `'amazonaws.com'`): root domain
-  recognized for virtual-host-style access.
-- `allowMismatchedSignatures` (boolean, default `false`): accept well-formed
-  but incorrect signatures.
-
-Anonymous (unsigned) requests are accepted, as on a public bucket, which is
-handy for plain `fetch`/`curl` in tests. Signed requests are verified against
-`accessKeyId`/`secretAccessKey`.
+```js
+// bucket configuration documents used below
+const corsXml = `<CORSConfiguration>
+  <CORSRule>
+    <AllowedOrigin>https://app.example.com</AllowedOrigin>
+    <AllowedMethod>GET</AllowedMethod>
+    <AllowedMethod>PUT</AllowedMethod>
+    <AllowedHeader>*</AllowedHeader>
+  </CORSRule>
+</CORSConfiguration>`;
+
+const websiteXml = `<WebsiteConfiguration>
+  <IndexDocument><Suffix>index.html</Suffix></IndexDocument>
+  <ErrorDocument><Key>error.html</Key></ErrorDocument>
+</WebsiteConfiguration>`;
+
+const policyJson = JSON.stringify({
+  Version: '2012-10-17',
+  Statement: [
+    {
+      Effect: 'Allow',
+      Principal: '*',
+      Action: 's3:GetObject',
+      Resource: 'arn:aws:s3:::site/public/*', // anonymous reads under public/ only
+    },
+  ],
+});
+
+const server = new S3TestServer({
+  // server
+  address: 'localhost', // hostname or IP the HTTP server binds to (default)
+  port: 4568, // listening port (default); 0 picks a free ephemeral port
+  key: fs.readFileSync('./key.pem'), // TLS private key; give key AND cert to
+  cert: fs.readFileSync('./cert.pem'), // serve HTTPS; omit both for HTTP (default)
+  silent: false, // default; true suppresses request and startup logging
+
+  // storage
+  directory: './s3-data', // where buckets and objects are stored, persisted
+  // across restarts; default: a fresh temporary directory per server
+  resetOnStart: false, // default; true empties the directory on every run()
+  resetOnClose: false, // default; true deletes all bucket data on close()
+  configureBuckets: [
+    // buckets created before the server starts; default: none
+    { name: 'assets', acl: 'public-read' }, // canned ACL (default: defaultBucketAcl)
+    { name: 'site', configs: [corsXml, websiteXml, policyJson] }, // raw CORS or
+    // website XML documents and bucket-policy JSON, applied at startup
+  ],
+
+  // credentials and addressing
+  accessKeyId: 'S3TEST', // access key id clients must sign with (default)
+  secretAccessKey: 'S3TEST', // matching SigV2/SigV4 secret key (default)
+  region: 'eu-west-1', // pinning a region rejects requests signed for others;
+  // omit to accept any region (reported as us-east-1)
+  defaultBucketAcl: 'private', // default, like real S3; ACL for buckets without
+  // one: 'private', 'public-read' (anonymous GETs) or 'public-read-write'
+  vhostBuckets: true, // default; resolve bucket.localhost and
+  // bucket.s3.<region>.amazonaws.com style Host headers to the bucket
+  serviceEndpoint: 'amazonaws.com', // default; root domain recognized for
+  // virtual-host-style addressing
+  allowMismatchedSignatures: false, // default; true accepts well-formed but
+  // incorrect signatures (useful with exotic clients)
+});
+```
+
+## Public and private buckets
+
+Like real S3, buckets are private by default. Signed requests are verified
+against `accessKeyId`/`secretAccessKey` and have full access. Anonymous
+(unsigned) requests are checked against the bucket's canned ACL:
+
+- `private` or `authenticated-read` (the default): all anonymous requests
+  get `403 AccessDenied`.
+- `public-read`: anonymous GET/HEAD only; anonymous writes get
+  `403 AccessDenied`.
+- `public-read-write`: anonymous reads and writes, like a fully public
+  bucket. Set `defaultBucketAcl: 'public-read-write'` to restore the 1.x
+  behavior where unsigned `fetch`/`curl` works everywhere.
+
+Set a bucket's ACL any of the usual ways:
+
+```js
+// at startup
+new S3TestServer({
+  configureBuckets: [
+    { name: 'assets', acl: 'public-read' },
+    { name: 'internal' }, // private, the default
+  ],
+});
+```
+
+```js
+// through the API
+await client.send(
+  new CreateBucketCommand({ Bucket: 'assets', ACL: 'public-read' })
+);
+await client.send(
+  new PutBucketAclCommand({ Bucket: 'assets', ACL: 'private' })
+);
+```
+
+`GetBucketAcl` reflects the canned ACL (an `AllUsers` grant appears for the
+public ones). Object-level ACLs are accepted but not enforced.
+
+### Per-prefix access with bucket policies
+
+For finer control than canned ACLs, the server evaluates a subset of bucket
+policies against anonymous requests: `Effect` Allow/Deny, `Principal` `"*"`,
+`Action` wildcards (`s3:GetObject`, `s3:ListBucket`, `s3:PutObject`,
+`s3:DeleteObject`, `s3:*`) and `Resource` ARNs with wildcards. Signed
+requests always have full access; an explicit `Deny` only narrows anonymous
+access. Set policies with `PutBucketPolicy`, or as a JSON document in
+`configureBuckets` (detected by its leading `{`):
+
+```js
+// only keys under public/ are readable without signing
+const policy = JSON.stringify({
+  Version: '2012-10-17',
+  Statement: [
+    {
+      Effect: 'Allow',
+      Principal: '*',
+      Action: 's3:GetObject',
+      Resource: 'arn:aws:s3:::site/public/*',
+    },
+  ],
+});
+new S3TestServer({ configureBuckets: [{ name: 'site', configs: [policy] }] });
+```
+
+Anonymous `GET /site/public/logo.png` then succeeds while
+`GET /site/internal/report.csv` and all anonymous writes return
+`403 AccessDenied`. `GetBucketPolicy` returns the stored document and
+`DeleteBucketPolicy` removes it. `NotAction`, `NotResource`, `NotPrincipal`
+and `Condition` are rejected as `NotImplemented` rather than silently
+ignored.
 
 ## Supported operations
 
@@ -158,7 +249,8 @@ handy for plain `fetch`/`curl` in tests. Signed requests are verified against
   Get/Put/DeleteBucketTagging
 - GetBucketVersioning, GetBucketEncryption, GetBucketNotification,
   GetBucketRequestPayment, GetBucketLogging, GetBucketAccelerate
-- Bucket ACLs (dummy responses)
+- Bucket ACLs (canned, enforced for anonymous requests)
+- Bucket policies (anonymous-access subset): Get/Put/DeleteBucketPolicy
 
 ### Objects
 
@@ -188,7 +280,7 @@ handy for plain `fetch`/`curl` in tests. Signed requests are verified against
 - Index and error documents, folder redirects
 - `x-amz-website-redirect-location` and `RedirectAllRequestsTo`
 - Served for anonymous GET/HEAD requests on buckets with a website
-  configuration
+  configuration; make the bucket `public-read`, as on real S3
 
 ### CORS
 
@@ -216,6 +308,33 @@ server.on('event', (notification) => {
 Emitted for `ObjectCreated:Put`, `ObjectCreated:Copy`, `ObjectCreated:Post`,
 `ObjectCreated:CompleteMultipartUpload` and `ObjectRemoved:Delete`.
 
+## Test helpers
+
+Three helpers make assertions and fixtures easy without building an S3
+client; they talk to the store directly:
+
+```js
+// seed fixtures (bucket is created if missing; no events are emitted)
+await server.putObjects('reports', [
+  { key: 'public/a.csv', body: 'a,b,c', contentType: 'text/csv' },
+  { key: 'internal/b.csv', body: Buffer.from('d,e,f') },
+]);
+
+// inspect bucket contents in assertions
+const all = await server.getObjects('reports');
+const csvs = await server.getObjects('reports', {
+  prefix: 'public/',
+  bodies: true, // each summary gets a `body` Buffer
+});
+
+// wait for background uploads from the code under test;
+// multipart uploads only count once completed
+const files = await server.waitForObjects('reports', 2, { timeout: 5000 });
+```
+
+After `run()` resolves, `server.hostPort` (`"localhost:4568"`) and
+`server.endpoint` (`"http://localhost:4568"`) are also set on the instance.
+
 ## Using as middleware
 
 ```js
@@ -234,6 +353,9 @@ http.createServer(s3.callback()).listen(4568);
 - `callback()` / `getMiddleware()` returns a request handler
 - `configureBuckets()` provisions `options.configureBuckets` without the API
 - `reset()` deletes all buckets and configurations
+- `getObjects(bucket, { prefix, bodies })` lists completed objects
+- `waitForObjects(bucket, count, { prefix, timeout })` awaits uploads
+- `putObjects(bucket, objects)` seeds fixtures without the HTTP API
 
 TypeScript definitions ship with the package (`lib/index.d.ts`).
 

package/lib/cli.js

@@ -14,7 +14,10 @@ Options:
   -d, --directory <path>           Data directory (default: a temporary directory)
       --access-key-id <id>         Access key clients must sign with (default: S3TEST)
       --secret-access-key <key>    Matching secret access key (default: S3TEST)
-      --region <region>            Region reported by the server (default: us-east-1)
+      --region <region>            Pin the server's region; requests signed for other
+                                   regions are rejected (default: accept any, report us-east-1)
+      --default-bucket-acl <acl>   ACL for buckets without one: private (default),
+                                   public-read, public-read-write, authenticated-read
       --key <path>                 Path to a private key file for HTTPS
       --cert <path>                Path to a certificate file for HTTPS
       --service-endpoint <host>    Root domain for virtual-host-style access
@@ -69,6 +72,9 @@ function parseArgs(argv) {
       case '--region':
         options.region = next();
         break;
+      case '--default-bucket-acl':
+        options.defaultBucketAcl = next();
+        break;
       case '--key':
         options.key = fs.readFileSync(next());
         break;

package/lib/controllers/bucket.js

@@ -18,15 +18,58 @@ const {
   DUMMY_OWNER,
 } = require('../utils');
 
-const dummyAclXml = () =>
-  '<?xml version="1.0" encoding="UTF-8"?>\n' +
-  `<AccessControlPolicy xmlns="${S3_XMLNS}">` +
-  `<Owner><ID>${DUMMY_OWNER.ID}</ID><DisplayName>${DUMMY_OWNER.DisplayName}</DisplayName></Owner>` +
-  '<AccessControlList><Grant>' +
-  '<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">' +
-  `<ID>${DUMMY_OWNER.ID}</ID><DisplayName>${DUMMY_OWNER.DisplayName}</DisplayName></Grantee>` +
-  '<Permission>FULL_CONTROL</Permission>' +
-  '</Grant></AccessControlList></AccessControlPolicy>';
+const CANNED_ACLS = new Set([
+  'private',
+  'public-read',
+  'public-read-write',
+  'authenticated-read',
+]);
+
+const ALL_USERS_URI = 'http://acs.amazonaws.com/groups/global/AllUsers';
+
+function groupGrant(permission) {
+  return (
+    '<Grant>' +
+    '<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">' +
+    `<URI>${ALL_USERS_URI}</URI></Grantee>` +
+    `<Permission>${permission}</Permission>` +
+    '</Grant>'
+  );
+}
+
+/** Renders an AccessControlPolicy document reflecting a canned ACL. */
+function aclXml(acl = 'private') {
+  let grants =
+    '<Grant>' +
+    '<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">' +
+    `<ID>${DUMMY_OWNER.ID}</ID><DisplayName>${DUMMY_OWNER.DisplayName}</DisplayName></Grantee>` +
+    '<Permission>FULL_CONTROL</Permission>' +
+    '</Grant>';
+  if (acl === 'public-read' || acl === 'public-read-write') {
+    grants += groupGrant('READ');
+  }
+  if (acl === 'public-read-write') {
+    grants += groupGrant('WRITE');
+  }
+  return (
+    '<?xml version="1.0" encoding="UTF-8"?>\n' +
+    `<AccessControlPolicy xmlns="${S3_XMLNS}">` +
+    `<Owner><ID>${DUMMY_OWNER.ID}</ID><DisplayName>${DUMMY_OWNER.DisplayName}</DisplayName></Owner>` +
+    `<AccessControlList>${grants}</AccessControlList></AccessControlPolicy>`
+  );
+}
+
+const dummyAclXml = () => aclXml('private');
+
+function validateCannedAcl(acl) {
+  if (!CANNED_ACLS.has(acl)) {
+    throw new S3Error('InvalidArgument', 'The ACL you provided is not valid', {
+      ArgumentName: 'x-amz-acl',
+      ArgumentValue: acl,
+    });
+  }
+  return acl;
+}
 
 async function requireBucket(ctx) {
   const meta = await ctx.store.getBucket(ctx.bucket);
@@ -56,8 +99,8 @@ async function getBucket(ctx) {
     return;
   }
   if (query.has('acl')) {
-    await requireBucket(ctx);
-    sendXml(res, 200, dummyAclXml());
+    const meta = await requireBucket(ctx);
+    sendXml(res, 200, aclXml(meta.configs.acl || ctx.options.defaultBucketAcl));
     return;
   }
   if (query.has('cors')) {
@@ -110,14 +153,23 @@ async function getBucket(ctx) {
     return;
   }
   if (query.has('policy')) {
-    await requireBucket(ctx);
-    throw new S3Error(
-      'NoSuchBucketPolicy',
-      'The bucket policy does not exist',
-      {
-        BucketName: ctx.bucket,
-      }
+    const meta = await requireBucket(ctx);
+    if (!meta.configs.policy) {
+      throw new S3Error(
+        'NoSuchBucketPolicy',
+        'The bucket policy does not exist',
+        {
+          BucketName: ctx.bucket,
+        }
+      );
+    }
+    send(
+      res,
+      200,
+      { 'Content-Type': 'application/json' },
+      meta.configs.policy.json
     );
+    return;
   }
   if (query.has('lifecycle')) {
     await requireBucket(ctx);
@@ -486,9 +538,26 @@ async function putBucket(ctx) {
   if (query.has('acl')) {
     await requireBucket(ctx);
     await readBody(ctx.req);
+    const acl = ctx.req.headers['x-amz-acl'];
+    if (acl) {
+      await ctx.store.putBucketConfig(
+        ctx.bucket,
+        'acl',
+        validateCannedAcl(String(acl))
+      );
+    }
     send(res, 200, {});
     return;
   }
+  if (query.has('policy')) {
+    await requireBucket(ctx);
+    const body = await readBody(ctx.req);
+    const { parseBucketPolicy } = require('../models/policy');
+    const policy = parseBucketPolicy(body.toString('utf8'));
+    await ctx.store.putBucketConfig(ctx.bucket, 'policy', policy);
+    send(res, 204, {});
+    return;
+  }
   if (query.has('versioning')) {
     await requireBucket(ctx);
     const body = await readBody(ctx.req);
@@ -512,7 +581,6 @@ async function putBucket(ctx) {
   }
   const knownUnsupported = [
     'lifecycle',
-    'policy',
     'encryption',
     'object-lock',
     'publicAccessBlock',
@@ -553,10 +621,26 @@ async function putBucket(ctx) {
       );
     }
   }
+  if (
+    ctx.options.enforceRegion &&
+    location &&
+    location !== ctx.options.region
+  ) {
+    throw new S3Error(
+      'IllegalLocationConstraintException',
+      `The ${location} location constraint is incompatible for the region specific endpoint this request was sent to.`,
+      { statusCode: 400 }
+    );
+  }
+  const acl = ctx.req.headers['x-amz-acl'];
+  if (acl) validateCannedAcl(String(acl));
   const { created } = await ctx.store.createBucket(ctx.bucket);
   if (created && location) {
     await ctx.store.putBucketConfig(ctx.bucket, 'location', location);
   }
+  if (created && acl) {
+    await ctx.store.putBucketConfig(ctx.bucket, 'acl', String(acl));
+  }
   // Matching us-east-1 behavior: re-creating a bucket you own succeeds.
   send(ctx.res, 200, { Location: `/${ctx.bucket}` });
 }
@@ -570,7 +654,7 @@ async function deleteBucket(ctx) {
     website: 'website',
     tagging: 'tagging',
     lifecycle: null,
-    policy: null,
+    policy: 'policy',
     encryption: null,
     publicAccessBlock: null,
     replication: null,
@@ -618,6 +702,7 @@ module.exports = {
   deleteBucket,
   headBucket,
   dummyAclXml,
+  validateCannedAcl,
   parseCorsConfig,
   parseWebsiteConfig,
   parseTaggingConfig,

package/lib/index.d.ts

@@ -11,6 +11,12 @@ declare class S3TestServer extends EventEmitter {
   /** The underlying HTTP(S) server, available after `run()` resolves. */
   httpServer: HttpServer | null;
 
+  /** `host:port` the server listens on; set once `run()` resolves. */
+  hostPort: string | null;
+
+  /** Full endpoint URL (e.g. `http://localhost:4568`); set once `run()` resolves. */
+  endpoint: string | null;
+
   /** Starts the server. */
   run(): Promise<S3TestServer.RunAddress>;
   run(
@@ -32,6 +38,34 @@ declare class S3TestServer extends EventEmitter {
   /** Deletes all buckets, objects and configurations in the store. */
   reset(): Promise<void>;
 
+  /**
+   * Lists the completed objects in a bucket, sorted by key. With
+   * `bodies: true`, each summary also carries its content as a Buffer.
+   */
+  getObjects(
+    bucket: string,
+    options?: { prefix?: string; bodies?: boolean }
+  ): Promise<S3TestServer.ObjectSummary[]>;
+
+  /**
+   * Resolves with the bucket's objects once at least `count` exist
+   * (optionally under `prefix`); rejects after `timeout` ms (default 10000).
+   */
+  waitForObjects(
+    bucket: string,
+    count: number,
+    options?: { prefix?: string; timeout?: number }
+  ): Promise<S3TestServer.ObjectSummary[]>;
+
+  /**
+   * Seeds objects directly into the store (the bucket is created when
+   * missing). No S3 event notifications are emitted for seeded objects.
+   */
+  putObjects(
+    bucket: string,
+    objects: S3TestServer.SeedObject[]
+  ): Promise<S3TestServer.ObjectSummary[]>;
+
   on(
     event: 'event',
     listener: (notification: S3TestServer.S3EventNotification) => void
@@ -48,14 +82,21 @@ declare namespace S3TestServer {
   interface BucketConfiguration {
     /** Bucket name (must be a valid S3 bucket name). */
     name: string;
+    /** Canned ACL applied to the bucket. Default: the server's `defaultBucketAcl`. */
+    acl?: CannedBucketAcl;
     /**
-     * Raw XML configuration documents applied to the bucket at startup.
-     * CORS (`<CORSConfiguration>`), website (`<WebsiteConfiguration>`) and
-     * tagging (`<Tagging>`) documents are recognized by their root element.
+     * Raw configuration documents applied to the bucket at startup.
+     * XML documents are recognized by their root element: CORS
+     * (`<CORSConfiguration>`), website (`<WebsiteConfiguration>`) and tagging
+     * (`<Tagging>`). A JSON document (leading `{`) is stored as the bucket
+     * policy and evaluated for anonymous requests.
      */
     configs?: Array<string | Buffer>;
   }
 
+  type CannedBucketAcl =
+    'private' | 'public-read' | 'public-read-write' | 'authenticated-read';
+
   interface S3TestServerOptions {
     /** Hostname or IP to bind to. Default: `"localhost"`. */
     address?: string;
@@ -95,8 +136,20 @@ declare namespace S3TestServer {
     accessKeyId?: string;
     /** Secret access key clients must sign requests with. Default: `"S3TEST"`. */
     secretAccessKey?: string;
-    /** Region reported in responses and event records. Default: `"us-east-1"`. */
+    /**
+     * Region reported in responses and event records. Default: `"us-east-1"`.
+     * When set explicitly, the server acts like a regional endpoint and
+     * rejects SigV4 requests signed for other regions; when omitted, any
+     * region is accepted.
+     */
     region?: string;
+    /**
+     * ACL for buckets without an explicit one. `'private'` (the default, like
+     * real S3) rejects anonymous requests; `'public-read'` allows anonymous
+     * GET/HEAD only; `'public-read-write'` restores the fully public 1.x
+     * behavior.
+     */
+    defaultBucketAcl?: CannedBucketAcl;
     /** Buckets to create (and configure) before the server starts. */
     configureBuckets?: BucketConfiguration[];
   }
@@ -116,14 +169,37 @@ declare namespace S3TestServer {
         | 'accessKeyId'
         | 'secretAccessKey'
         | 'region'
+        | 'defaultBucketAcl'
       >
     >;
 
+  interface ObjectSummary {
+    key: string;
+    size: number;
+    /** Hex ETag without quotes. */
+    etag: string;
+    lastModified: Date;
+    contentType?: string;
+    /** User metadata (`x-amz-meta-*`), with the prefix stripped. */
+    metadata: Record<string, string>;
+    /** Present when requested with `bodies: true`. */
+    body?: Buffer;
+  }
+
+  interface SeedObject {
+    key: string;
+    body: string | Buffer;
+    contentType?: string;
+    metadata?: Record<string, string>;
+  }
+
   interface RunAddress {
     /** Bound address, as reported by `net.Server#address()`. */
     address: string;
     family: string;
     port: number;
+    /** `host:port` the server listens on. */
+    hostPort: string;
     /** `"http"` or `"https"`. */
     protocol: string;
     /** Convenience endpoint URL, e.g. `"http://localhost:4568"`. */
@@ -178,6 +254,9 @@ declare namespace S3TestServer {
 
   export {
     S3TestServer,
+    ObjectSummary,
+    SeedObject,
+    CannedBucketAcl,
     BucketConfiguration,
     S3TestServerOptions,
     ResolvedOptions,

package/lib/index.js

@@ -26,6 +26,9 @@ const DEFAULT_OPTIONS = {
   accessKeyId: 'S3TEST',
   secretAccessKey: 'S3TEST',
   region: 'us-east-1',
+  // Like real S3, buckets are private by default: anonymous requests get
+  // 403 AccessDenied unless the bucket's ACL makes it public.
+  defaultBucketAcl: 'private',
   configureBuckets: [],
 };
 
@@ -33,6 +36,12 @@ class S3TestServer extends EventEmitter {
   constructor(options = {}) {
     super();
     this.options = { ...DEFAULT_OPTIONS, ...options };
+    // When the user pins a region, behave like a regional endpoint and
+    // reject requests signed for other regions. Otherwise accept any.
+    this.options.enforceRegion = Object.prototype.hasOwnProperty.call(
+      options,
+      'region'
+    );
     this.logger = {
       info: (...args) => {
         if (!this.options.silent) console.log(...args);
@@ -43,6 +52,8 @@ class S3TestServer extends EventEmitter {
     };
     this.httpServer = null;
     this.store = null;
+    this.hostPort = null;
+    this.endpoint = null;
     this._middleware = null;
     this._sequencer = 0;
   }
@@ -101,13 +112,14 @@ class S3TestServer extends EventEmitter {
       });
       const address = this.httpServer.address();
       const protocol = this.options.key && this.options.cert ? 'https' : 'http';
-      this.logger.info(
-        `S3 test server listening on ${protocol}://${this.options.address}:${address.port}`
-      );
+      this.hostPort = `${this.options.address}:${address.port}`;
+      this.endpoint = `${protocol}://${this.hostPort}`;
+      this.logger.info(`S3 test server listening on ${this.endpoint}`);
       return {
         ...address,
         protocol,
-        endpoint: `${protocol}://${this.options.address}:${address.port}`,
+        hostPort: this.hostPort,
+        endpoint: this.endpoint,
       };
     })();
     if (typeof callback === 'function') {
@@ -157,16 +169,28 @@ class S3TestServer extends EventEmitter {
       parseCorsConfig,
       parseWebsiteConfig,
       parseTaggingConfig,
+      validateCannedAcl,
     } = require('./controllers/bucket');
     const { validateBucketName } = require('./utils');
-    for (const { name, configs = [] } of this.options.configureBuckets || []) {
+    for (const { name, configs = [], acl } of this.options.configureBuckets ||
+      []) {
       validateBucketName(name);
       await this.store.createBucket(name);
+      if (acl) {
+        await this.store.putBucketConfig(name, 'acl', validateCannedAcl(acl));
+      }
       for (const rawConfig of configs) {
         const xml = Buffer.isBuffer(rawConfig)
           ? rawConfig.toString('utf8')
           : String(rawConfig);
-        if (/<\s*(\w+:)?CORSConfiguration[\s>]/.test(xml)) {
+        if (/^\s*\{/.test(xml)) {
+          const { parseBucketPolicy } = require('./models/policy');
+          await this.store.putBucketConfig(
+            name,
+            'policy',
+            parseBucketPolicy(xml)
+          );
+        } else if (/<\s*(\w+:)?CORSConfiguration[\s>]/.test(xml)) {
           await this.store.putBucketConfig(name, 'cors', parseCorsConfig(xml));
         } else if (/<\s*(\w+:)?WebsiteConfiguration[\s>]/.test(xml)) {
           await this.store.putBucketConfig(
@@ -196,6 +220,143 @@ class S3TestServer extends EventEmitter {
     await this.store.reset();
   }
 
+  // ---------------------------------------------------------------- helpers
+
+  _toSummary(meta) {
+    return {
+      key: meta.key,
+      size: meta.size,
+      etag: meta.etag,
+      lastModified: new Date(meta.lastModified),
+      contentType: meta.contentType,
+      metadata: { ...(meta.userMetadata || {}) },
+    };
+  }
+
+  /**
+   * Lists the completed objects in a bucket (multipart parts in flight are
+   * never included), sorted by key. With `bodies: true`, each entry also
+   * carries its content as a Buffer.
+   */
+  async getObjects(bucket, { prefix = '', bodies = false } = {}) {
+    this._ensureStore();
+    if (!(await this.store.getBucket(bucket))) {
+      throw new S3Error('NoSuchBucket', 'The specified bucket does not exist', {
+        BucketName: bucket,
+      });
+    }
+    const metas = (await this.store.listObjects(bucket)).filter(
+      (meta) => !prefix || meta.key.startsWith(prefix)
+    );
+    const summaries = metas.map((meta) => this._toSummary(meta));
+    if (bodies) {
+      for (const summary of summaries) {
+        summary.body = await this._readObject(bucket, summary.key);
+      }
+    }
+    return summaries;
+  }
+
+  _readObject(bucket, key) {
+    return new Promise((resolve, reject) => {
+      const chunks = [];
+      this.store
+        .createObjectReadStream(bucket, key)
+        .on('data', (chunk) => chunks.push(chunk))
+        .on('end', () => resolve(Buffer.concat(chunks)))
+        .on('error', reject);
+    });
+  }
+
+  /**
+   * Resolves with the bucket's objects once at least `count` of them exist
+   * (optionally under `prefix`). Useful when the code under test uploads in
+   * the background. A bucket that does not exist yet simply counts as empty.
+   */
+  async waitForObjects(bucket, count, { prefix = '', timeout = 10000 } = {}) {
+    this._ensureStore();
+    const matching = async () => {
+      if (!(await this.store.getBucket(bucket))) return null;
+      const metas = (await this.store.listObjects(bucket)).filter(
+        (meta) => !prefix || meta.key.startsWith(prefix)
+      );
+      return metas.length >= count
+        ? metas.map((meta) => this._toSummary(meta))
+        : null;
+    };
+
+    const found = await matching();
+    if (found) return found;
+
+    return new Promise((resolve, reject) => {
+      let interval;
+      let timer;
+      const check = async () => {
+        const objects = await matching().catch(() => null);
+        if (objects) {
+          cleanup();
+          resolve(objects);
+        }
+      };
+      const cleanup = () => {
+        clearInterval(interval);
+        clearTimeout(timer);
+        this.removeListener('event', check);
+      };
+      this.on('event', check);
+      // Poll as well, so out-of-band writes (e.g. putObjects) are seen too.
+      interval = setInterval(check, 150);
+      timer = setTimeout(() => {
+        cleanup();
+        reject(
+          new Error(
+            `Timed out after ${timeout}ms waiting for ${count} object(s) in "${bucket}"` +
+              (prefix ? ` under "${prefix}"` : '')
+          )
+        );
+      }, timeout);
+    });
+  }
+
+  /**
+   * Seeds objects directly into the store, bypassing the HTTP API. The
+   * bucket is created when missing. Each entry is
+   * `{ key, body, contentType?, metadata? }` with a string or Buffer body.
+   * No S3 event notifications are emitted for seeded objects.
+   */
+  async putObjects(bucket, objects) {
+    this._ensureStore();
+    await this.store.initialize();
+    const { validateBucketName } = require('./utils');
+    validateBucketName(bucket);
+    await this.store.createBucket(bucket);
+    const { Readable } = require('stream');
+    const results = [];
+    for (const object of objects) {
+      if (!object || typeof object.key !== 'string') {
+        throw new TypeError('putObjects entries need a string `key`');
+      }
+      const body = Buffer.isBuffer(object.body)
+        ? object.body
+        : Buffer.from(object.body ?? '');
+      const staged = await this.store.stageObject(
+        bucket,
+        Readable.from([body]),
+        ['CRC64NVME']
+      );
+      const meta = await staged.commit(object.key, {
+        contentType: object.contentType || 'binary/octet-stream',
+        userMetadata: { ...(object.metadata || {}) },
+        tagging: {},
+        checksums: staged.digests.checksums,
+        checksumAlgorithm: 'CRC64NVME',
+        checksumType: 'FULL_OBJECT',
+      });
+      results.push(this._toSummary(meta));
+    }
+    return results;
+  }
+
   _emitEvent(eventName, bucket, objectMeta) {
     if (!objectMeta) return;
     this._sequencer += 1;

package/lib/models/policy.js

@@ -0,0 +1,124 @@
+'use strict';
+
+const { S3Error } = require('./error');
+
+/**
+ * A small subset of S3 bucket policies, used to grant anonymous access per
+ * key prefix (e.g. make only `public/*` readable without signing).
+ *
+ * Supported: Effect Allow/Deny, Principal "*" (or {"AWS": "*"}), Action
+ * strings with wildcards (s3:GetObject, s3:ListBucket, s3:PutObject,
+ * s3:DeleteObject, s3:*), Resource ARNs with * and ? wildcards.
+ *
+ * Statements with other principals are stored but never match anonymous
+ * requests. Signed requests always have full access, so policies only widen
+ * or narrow what anonymous callers may do.
+ */
+
+function asList(value) {
+  if (value === undefined || value === null) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+function malformed(message) {
+  return new S3Error('MalformedPolicy', message, { statusCode: 400 });
+}
+
+const UNSUPPORTED_FIELDS = [
+  'NotAction',
+  'NotResource',
+  'NotPrincipal',
+  'Condition',
+];
+
+function parseBucketPolicy(text) {
+  let doc;
+  try {
+    doc = JSON.parse(text);
+  } catch {
+    throw malformed('Policies must be valid JSON and the first byte must be {');
+  }
+  const rawStatements = asList(doc.Statement);
+  if (rawStatements.length === 0) {
+    throw malformed('Missing required field Statement');
+  }
+  const statements = rawStatements.map((statement) => {
+    if (typeof statement !== 'object' || statement === null) {
+      throw malformed('Statement must be an object or an array of objects');
+    }
+    for (const field of UNSUPPORTED_FIELDS) {
+      if (statement[field] !== undefined) {
+        throw new S3Error(
+          'NotImplemented',
+          `Bucket policy element ${field} is not supported by this server`
+        );
+      }
+    }
+    const effect = statement.Effect;
+    if (effect !== 'Allow' && effect !== 'Deny') {
+      throw malformed('Statement Effect must be Allow or Deny');
+    }
+    let principals;
+    if (statement.Principal === '*') {
+      principals = ['*'];
+    } else if (statement.Principal && typeof statement.Principal === 'object') {
+      principals = asList(statement.Principal.AWS).map(String);
+    } else if (statement.Principal === undefined) {
+      throw malformed('Missing required field Principal');
+    } else {
+      principals = [String(statement.Principal)];
+    }
+    const actions = asList(statement.Action).map((action) =>
+      String(action).toLowerCase()
+    );
+    if (actions.length === 0) {
+      throw malformed('Missing required field Action');
+    }
+    const resources = asList(statement.Resource).map(String);
+    if (resources.length === 0) {
+      throw malformed('Missing required field Resource');
+    }
+    return { effect, principals, actions, resources };
+  });
+  return {
+    json: typeof text === 'string' ? text : JSON.stringify(doc),
+    statements,
+  };
+}
+
+function wildcardMatch(pattern, value) {
+  const regex = new RegExp(
+    '^' +
+      String(pattern)
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*/g, '.*')
+        .replace(/\?/g, '.') +
+      '$'
+  );
+  return regex.test(value);
+}
+
+/**
+ * Evaluates a parsed policy for an anonymous request.
+ * Returns 'deny', 'allow' or 'none' (no matching statement).
+ */
+function evaluateBucketPolicy(policy, action, resource) {
+  const wantedAction = action.toLowerCase();
+  let allowed = false;
+  for (const statement of policy.statements) {
+    if (!statement.principals.includes('*')) continue;
+    const actionMatches = statement.actions.some((pattern) =>
+      wildcardMatch(pattern, wantedAction)
+    );
+    const resourceMatches = statement.resources.some((pattern) =>
+      wildcardMatch(pattern, resource)
+    );
+    if (actionMatches && resourceMatches) {
+      if (statement.effect === 'Deny') return 'deny';
+      allowed = true;
+    }
+  }
+  return allowed ? 'allow' : 'none';
+}
+
+module.exports = { parseBucketPolicy, evaluateBucketPolicy };

package/lib/routes.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { S3Error } = require('./models/error');
+const { evaluateBucketPolicy } = require('./models/policy');
 const { authenticate } = require('./signature');
 const { generateRequestId, generateId2 } = require('./utils');
 const { resolveVhostBucket } = require('./middleware/vhost');
@@ -82,9 +83,44 @@ async function handleRequest(server, req, res) {
   }
   applyCorsHeaders(ctx, corsConfig);
 
-  // Authentication (anonymous requests are allowed, like public buckets)
+  // Authentication (anonymous requests are allowed on public buckets)
   ctx.auth = authenticate({ req, rawPath, query, vhostBucket, options });
 
+  // Bucket access control: anonymous requests are checked against the
+  // bucket's canned ACL, then against its bucket policy (which can widen
+  // access per key prefix, or deny it). Signed requests have full access.
+  if (bucket && bucketMeta && ctx.auth.mode === 'anonymous') {
+    const acl = bucketMeta.configs.acl || options.defaultBucketAcl;
+    const isRead = req.method === 'GET' || req.method === 'HEAD';
+    let allowed =
+      acl === 'public-read-write' || (acl === 'public-read' && isRead);
+    const policy = bucketMeta.configs.policy;
+    if (policy) {
+      let action = null;
+      let resource;
+      if (key) {
+        resource = `arn:aws:s3:::${bucket}/${key}`;
+        if (isRead) action = 's3:GetObject';
+        else if (req.method === 'DELETE') action = 's3:DeleteObject';
+        else action = 's3:PutObject';
+      } else if (isRead) {
+        resource = `arn:aws:s3:::${bucket}`;
+        action = 's3:ListBucket';
+      } else if (req.method === 'POST') {
+        resource = `arn:aws:s3:::${bucket}/*`;
+        action = query.has('delete') ? 's3:DeleteObject' : 's3:PutObject';
+      }
+      if (action) {
+        const verdict = evaluateBucketPolicy(policy, action, resource);
+        if (verdict === 'allow') allowed = true;
+        else if (verdict === 'deny') allowed = false;
+      }
+    }
+    if (!allowed) {
+      throw new S3Error('AccessDenied', 'Access Denied');
+    }
+  }
+
   // Static website hosting
   if (isWebsiteRequest(ctx, bucketMeta)) {
     await serveWebsite(ctx, bucketMeta.configs.website);

package/lib/signature/v4.js

@@ -93,6 +93,13 @@ function verifyV4Header({ req, rawPath, query, authHeader, options }) {
   }
   const [accessKeyId, credDate, region] = credParts;
   checkAccessKey(accessKeyId, options);
+  if (options.enforceRegion && region !== options.region) {
+    throw new S3Error(
+      'AuthorizationHeaderMalformed',
+      `The authorization header is malformed; the region '${region}' is wrong; expecting '${options.region}'`,
+      { Region: options.region }
+    );
+  }
 
   const amzDate = req.headers['x-amz-date'];
   const dateMs = amzDate
@@ -175,7 +182,20 @@ function verifyV4Query({ req, rawPath, query, options }) {
     );
   }
   const [accessKeyId, credDate, region] = credParts;
+  if (credParts[3] !== 's3' || credParts[4] !== 'aws4_request') {
+    throw new S3Error(
+      'AuthorizationQueryParametersError',
+      'Error parsing the X-Amz-Credential parameter; the credential scope is incorrect.'
+    );
+  }
   checkAccessKey(accessKeyId, options);
+  if (options.enforceRegion && region !== options.region) {
+    throw new S3Error(
+      'AuthorizationQueryParametersError',
+      `Error parsing the X-Amz-Credential parameter; the region '${region}' is wrong; expecting '${options.region}'`,
+      { Region: options.region }
+    );
+  }
 
   const dateMs = parseAmzDate(amzDate);
   if (Number.isNaN(dateMs)) {

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "s3-test-server",
-  "version": "1.0.1",
+  "version": "2.1.0",
   "description": "A modern, lightweight Amazon S3 emulator for local development and testing. Compatible with AWS SDK v2 and v3, Signature V2/V4, path-style and virtual-host-style addressing, streaming (aws-chunked) uploads and flexible checksums.",
   "license": "MIT",
   "author": "Israel Alagbe <israelalagbe53@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/israelalagbe/s3-test-server.git"
+  },
+  "homepage": "https://github.com/israelalagbe/s3-test-server#readme",
+  "bugs": {
+    "url": "https://github.com/israelalagbe/s3-test-server/issues"
+  },
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "bin": {