s3-test-server 1.0.0 → 2.0.0

package/README.md

@@ -82,7 +82,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,72 +108,197 @@ 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
+```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
 
-| Option         | Type               | Default       | Description                                       |
-| -------------- | ------------------ | ------------- | ------------------------------------------------- |
-| `address`      | `string`           | `'localhost'` | Hostname or IP to bind to.                        |
-| `port`         | `number`           | `4568`        | Port to listen on. Use `0` for an ephemeral port. |
-| `key` / `cert` | `string \| Buffer` | none          | TLS key and certificate. Provide both for HTTPS.  |
-| `silent`       | `boolean`          | `false`       | Suppress log output.                              |
+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:
 
-### Storage
+- `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.
 
-| Option             | Type                    | Default  | Description                                                                                |
-| ------------------ | ----------------------- | -------- | ------------------------------------------------------------------------------------------ |
-| `directory`        | `string`                | temp dir | Where buckets and objects are stored. Data persists across restarts.                       |
-| `resetOnStart`     | `boolean`               | `false`  | Clear the data directory on every start, so a persistent `directory` begins empty.         |
-| `resetOnClose`     | `boolean`               | `false`  | Delete all bucket data when `close()` is called.                                           |
-| `configureBuckets` | `BucketConfiguration[]` | `[]`     | Buckets to create at startup, each with optional raw XML configs (CORS, website, tagging). |
+Set a bucket's ACL any of the usual ways:
 
-### Credentials and addressing
+```js
+// at startup
+new S3TestServer({
+  configureBuckets: [
+    { name: 'assets', acl: 'public-read' },
+    { name: 'internal' }, // private, the default
+  ],
+});
+```
 
-| Option                      | Type      | Default           | Description                                                                             |
-| --------------------------- | --------- | ----------------- | --------------------------------------------------------------------------------------- |
-| `accessKeyId`               | `string`  | `'S3TEST'`        | Access key clients must sign with.                                                      |
-| `secretAccessKey`           | `string`  | `'S3TEST'`        | Matching secret key.                                                                    |
-| `region`                    | `string`  | `'us-east-1'`     | Region reported in responses and event records.                                         |
-| `vhostBuckets`              | `boolean` | `true`            | Virtual-host-style addressing (`bucket.localhost`, `bucket.s3.<region>.amazonaws.com`). |
-| `serviceEndpoint`           | `string`  | `'amazonaws.com'` | Root domain recognized for virtual-host-style access.                                   |
-| `allowMismatchedSignatures` | `boolean` | `false`           | Accept well-formed but incorrect signatures.                                            |
+```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 (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`.
+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
 
-**Service / buckets**: ListBuckets, Create/Delete/HeadBucket,
-GetBucketLocation, ListObjects (v1), ListObjectsV2, ListObjectVersions
-(unversioned mapping), Get/Put/DeleteBucketCors, Get/Put/DeleteBucketWebsite,
-Get/Put/DeleteBucketTagging, GetBucketVersioning, GetBucketEncryption,
-GetBucketNotification/RequestPayment/Logging/Accelerate, ACLs (dummy),
-ListMultipartUploads.
-
-**Objects**: Put/Get/Head/DeleteObject, DeleteObjects, CopyObject
-(COPY/REPLACE directives, copy conditions), POST form uploads
-(`multipart/form-data`, `${filename}` substitution, `success_action_*`),
-Get/Put/DeleteObjectTagging, GetObjectAttributes, object ACLs (dummy),
-Range requests, conditional reads (`If-Match`, `If-None-Match`,
-`If-(Un)Modified-Since`) and **conditional writes** (`If-None-Match: *`,
-`If-Match`), `response-*` header overrides, `Content-MD5` and
-`x-amz-checksum-*` validation (headers or `aws-chunked` trailers).
-
-**Multipart**: Create/Abort/CompleteMultipartUpload, UploadPart,
-UploadPartCopy (with `x-amz-copy-source-range`), ListParts, correct
-multipart ETags (`md5-of-md5s-N`), composite and full-object checksums.
-
-**Static website hosting**: index/error documents, folder redirects,
-`x-amz-website-redirect-location`, `RedirectAllRequestsTo`; served for
-anonymous GET/HEAD requests on buckets with a website configuration.
-
-**CORS**: preflight (`OPTIONS`) evaluation and response headers, driven by
-the bucket's CORS configuration.
-
-Not implemented: bucket versioning (`PutBucketVersioning` with `Enabled`
-returns `NotImplemented`), object locking, lifecycle execution, bucket
-policies/IAM. Per-chunk signatures inside `aws-chunked` bodies are not
-re-verified (the seed signature is).
+### Service and buckets
+
+- ListBuckets, CreateBucket, DeleteBucket, HeadBucket, GetBucketLocation
+- ListObjects (v1), ListObjectsV2, ListObjectVersions (unversioned mapping)
+- ListMultipartUploads
+- Get/Put/DeleteBucketCors, Get/Put/DeleteBucketWebsite,
+  Get/Put/DeleteBucketTagging
+- GetBucketVersioning, GetBucketEncryption, GetBucketNotification,
+  GetBucketRequestPayment, GetBucketLogging, GetBucketAccelerate
+- Bucket ACLs (canned, enforced for anonymous requests)
+- Bucket policies (anonymous-access subset): Get/Put/DeleteBucketPolicy
+
+### Objects
+
+- PutObject, GetObject, HeadObject, DeleteObject, DeleteObjects
+- CopyObject with COPY/REPLACE directives and copy conditions
+- POST form uploads: `multipart/form-data`, `${filename}` substitution,
+  `success_action_*`
+- Get/Put/DeleteObjectTagging, GetObjectAttributes, object ACLs (dummy)
+- Range requests (`206 Partial Content`)
+- Conditional reads: `If-Match`, `If-None-Match`, `If-(Un)Modified-Since`
+- Conditional writes: `If-None-Match: *`, `If-Match`
+- `response-*` header overrides on GET
+- Integrity validation: `Content-MD5` and `x-amz-checksum-*`
+  (CRC32, CRC32C, CRC64NVME, SHA1, SHA256), from headers or `aws-chunked`
+  trailers
+
+### Multipart uploads
+
+- CreateMultipartUpload, UploadPart, UploadPartCopy (with
+  `x-amz-copy-source-range`), CompleteMultipartUpload, AbortMultipartUpload,
+  ListParts
+- Correct multipart ETags (`md5-of-md5s-N`)
+- Composite and full-object checksums
+
+### Static website hosting
+
+- 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; make the bucket `public-read`, as on real S3
+
+### CORS
+
+- Preflight (`OPTIONS`) evaluation and response headers, driven by the
+  bucket's CORS configuration
+
+### Not implemented
+
+- Bucket versioning (`PutBucketVersioning` with `Enabled` returns
+  `NotImplemented`), object locking, lifecycle execution, bucket policies/IAM
+- Per-chunk signatures inside `aws-chunked` bodies are not re-verified (the
+  seed signature is)
 
 ## Events
 

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

@@ -48,14 +48,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 +102,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,6 +135,7 @@ declare namespace S3TestServer {
         | 'accessKeyId'
         | 'secretAccessKey'
         | 'region'
+        | 'defaultBucketAcl'
       >
     >;
 
@@ -178,6 +198,7 @@ declare namespace S3TestServer {
 
   export {
     S3TestServer,
+    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);
@@ -157,16 +166,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(

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.0",
+  "version": "2.0.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": {